---
title: "API: listRoles"
slug: "api-listroles"
updated: 2022-08-30T19:46:02Z
published: 2022-08-30T19:46:02Z
canonical: "support.smarteru.com/api-listroles"
---

> ## 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: listRoles

- 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 listRoles method retrieves [learning plans](/v1/docs/learning-plans) that meet the specified filter.

## **Who Has Access**

The following users have access to the listRoles 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>listRoles</Method>    
   <Parameters>
      <Role>
         <Page><![CDATA[]]></Page>
         <Filters>
            <RoleStatus><![CDATA[]]></RoleStatus>
         </Filters>
      </Role>
   </Parameters>
</SmarterU>
```

## **Role Tag Group**

The Role tag group is a container for how the response is returned and the learning plan filter.

```markup
<Role>
   <Page><![CDATA[]]></Page>
   <Filters>
      <RoleStatus><![CDATA[]]></RoleStatus>
   </Filters>
</Role>
```

The Role tag may contain the following.

### **Page** (optional)

The page to get. Default is *1*. If the Page tag is not provided, up to 50 results are returned by default.

### **Filters** (optional)

A container for the learning plan status filter. This tag contains the following.

| Tag | Description |
| --- | --- |
| **RoleStatus** | The [learning plan status](/v1/docs/learning-plan-main#status) filter. Acceptable values are *Active*, *Inactive*, or *All*. The default is *All*. |

## 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-listroles#error-codes) tag.

```markup
<SmarterU>
    <Result></Result>
    <Info>
        <Roles>
            <Role>
                <Name><![CDATA[]]></Name>
                <RoleID><![CDATA[]]></RoleID>
                <Status></Status>
            </Role>
        </Roles>
    </Info>
    <Errors>
        <Error>
            <ErrorID></ErrorID>
            <ErrorMessage></ErrorMessage>
        </Error>
    </Errors>
</SmarterU>
```

The Roles tag is a container for the learning plans returned by the listRoles method. Each 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).

### Status

The [learning plan's status](/v1/docs/learning-plan-main#status) (i.e., Active, Inactive).

### Example API Response XML Package

Below is an example of an API response XML package.

```markup
<SmarterU>
    <Result>Success</Result>
    <Info>
        <Roles>
            <Role>
                <Name><!--[CDATA[Forklift Operator]]--></Name>
                <RoleID><!--[CDATA[LP-2093]]--></RoleID>
                <Status>Active</Status>
            </Role>

            <Role>
                <Name><!--[CDATA[Store Manager]]--></Name>
                <RoleID><!--[CDATA[LP-1020]]--></RoleID>
                <Status>Active</Status>
            </Role>
        </Roles>
    </Info>
</SmarterU>
```

## **Error Codes**

| Error Code | Message |
| --- | --- |
| LR:01 | The page number provided is not valid. |
| LR:02 | The learning plan status provided is not valid. |
| LR:03 | The required permissions are not met to call the listRoles method. |
| LR:04 | The value for a role status must be *Active*, *Inactive*, or *All*. |

## Related

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