---
title: "API: getRole"
slug: "api-getrole"
updated: 2022-08-30T18:24:00Z
published: 2022-08-30T18:24:00Z
canonical: "support.smarteru.com/api-getrole"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.smarteru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API: getRole

- Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
- If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
- Tags are required unless specified.

## Description

[Learning Plans](https://support.smarteru.com/docs/learning-plans) were previously referred to as *roles*. 

The getRole method retrieves a [learning plan's](/v1/docs/learning-plans) details.

## Who Has Access

The following users have access to the getRole method:

- Users with the [Manage Learning Plans, Certifications, and Requirements](/v1/docs/account-permission-manage-learning-plans-certifications-and-requirements) or [View Learning Plans, Certifications, and Requirements](/v1/docs/account-permission-view-learning-plans-certifications-and-requirements) account permission.
- [Administrators and owners](/v1/docs/user-profile-information#access-level).

## API Call XML Package

```markup
<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>getRole</Method>
   <Parameters>
      <Role>
         <Name><![CDATA[]]></Name>
            - OR -
         <RoleID><![CDATA[]]></RoleID>
      </Role>
   </Parameters>
</SmarterU>
```

## Role Tag Group

The Role tag group is a container for the learning plan filters.

```markup
<Role>
   <Name><![CDATA[]]></Name>
      - OR -
   <RoleID><![CDATA[]]></RoleID>
</Role>
```

The Role tag contains one of the following.

### Name

The [learning plan's name](/v1/docs/learning-plan-main#name). This tag is mutually exclusive with the [RoleID tag](/v1/docs/api-getrole#roleid).

### RoleID

The [learning plan's user-specified identifier](/v1/docs/learning-plan-main#learning-plan-id). This tag is mutually exclusive with the [Name tag](/v1/docs/api-getrole#name). This is the RoleID returned by the [listRoles](/v1/docs/api-listroles) method.

## API Response XML Package

The [API response XML package](/v1/docs/api-response-xml-package) will always include a Result, Info, and [Errors](/v1/docs/api-getrole#error-codes) tag.

```markup
<SmarterU>
   <Result></Result>
   <Info>
      <Role>
         <Name><![CDATA[]]></Name>
         <RoleID><![CDATA[]]></RoleID>
         <CreatedDate></CreatedDate>
         <ModifiedDate></ModifiedDate>
         <Description><![CDATA[]]></Description>
         <UserCount></UserCount>
         <CertificationCount></CertificationCount>
         <Status></Status>
      </Role>
   </Info>
   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>
```

The learning plan is contained in a Role tag and may contain the following.

### Name

The [learning plan's name](/v1/docs/learning-plan-main#name).

### RoleID

The [learning plan's user-specified identifier](/v1/docs/learning-plan-main#learning-plan-id).

### CreatedDate

The date the learning plan was [created](/v1/docs/adding-an-advanced-learning-plan).

### ModifiedDate

The date the learning plan was last [edited](/v1/docs/editing-a-learning-plan).

### Description

The [learning plan's description](/v1/docs/learning-plan-main#description).

### UserCount

The number of [users who are assigned the learning plan](/v1/docs/assigning-learning-plans-to-a-user).

### CertificationCount

The number of [certifications associated with the learning plan](/v1/docs/assigning-certifications-to-a-learning-plan).

### Status

The [learning plan's status](/v1/docs/learning-plan-main#status).

### Example API Response XML Package

Below is an example of an API response XML package.

```markup
<SmarterU>
   <Result>Success</Result>
   <Info>
      <Role>
         <Name><![CDATA[Forklift Operator]]></Name>
         <RoleID><![CDATA[LP-2093]]></RoleID>
         <CreatedDate>2014-06-17 20:31:31.33</CreatedDate>
         <ModifiedDate>2018-06-06 21:20:37.923</ModifiedDate>
         <Description><![CDATA[Forklift operators at Fina Shoes.]]></Description>
         <UserCount>12</UserCount>
         <CertificationCount>2</CertificationCount>
         <Status>Active</Status>
      </Role>
   </Info>
   <Errors>

   </Errors>
</SmarterU>
```

## **Error Codes**

| Error Code | Message |
| --- | --- |
| GR:01 | The name provided is not valid. |
| GR:02 | The required permissions are not met to call the getRole method. |
| GR:03 | The requested learning plan does not exist. |
| GR:04 | The learning plan ID provided is not valid. |

## Related

- [API: createRole](/api-createrole.md)
- [API: listRoles](/api-listroles.md)
- [API: updateRole](/api-updaterole.md)
- [Learning Plan Automation](/learning-plan-automation.md)
- [Learning Plans](/learning-plans.md)