---
title: "API: createRole"
slug: "api-createrole"
updated: 2022-08-30T16:48:34Z
published: 2022-08-30T16:48:34Z
canonical: "support.smarteru.com/api-createrole"
---

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

- SmarterU requires 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 createRole method [adds a learning plan](/v1/docs/adding-a-flat-learning-plan-page).

## Who Has Access

The following users have access to the createRole method:

- Users with the [Manage Learning Plans, Certifications, and Requirements](/v1/docs/account-permission-manage-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>createRole</Method>
   <Parameters>
      <Role>
         <Name><![CDATA[]]></Name>
         <RoleID><![CDATA[]]></RoleID>
         <Status><![CDATA[]]></Status>
         <Description><![CDATA[]]></Description>
         <Certifications>
            <Certification>
               <CertificationName><![CDATA[]]></CertificationName>
               <MandateLevel><![CDATA[]]></MandateLevel>
            </Certification>
         </Certifications>
      </Role>
   </Parameters>
</SmarterU>
```

## Role Tag Group

The Role tag group is a container for the learning plan's details.

```markup
<Role>
   <Name><![CDATA[]]></Name>
   <RoleID><![CDATA[]]></RoleID>
   <Status><![CDATA[]]></Status>
   <Description><![CDATA[]]></Description>
   <Certifications>
      <Certification>
         <CertificationName><![CDATA[]]></CertificationName>
         <MandateLevel><![CDATA[]]></MandateLevel>
      </Certification>
   </Certifications>
</Role>
```

The Role tag may contain the following.

### Name

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

### **RoleID** (optional tag)

A [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). Acceptable values are *Active* or *Inactive*.

### **Description**

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

### **Certifications**

A container for the learning plan's certifications. Refer to [Certifications Tag Group](/v1/docs/api-createrole#certifications-tag-group).

## **Certifications Tag Group**

The Certifications tag group is a container for the [learning plan's certifications](/v1/docs/assigning-certifications-to-a-learning-plan).

```markup
<Certifications>
   <Certification>
      <CertificationName><![CDATA[]]></CertificationName>
      <MandateLevel><![CDATA[]]></MandateLevel>
   </Certification>
</Certifications>
```

Each certification is contained in a Certification tag and may contain the following.

### CertificationName

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

### MandateLevel

The certification's mandate level. Acceptable values are:

- *Mandatory* - The certification is required for the learning plan.
- *Recommended* - The certification is not required, but recommended for the learning plan.
- *Optional* - The certification is optional for the learning plan.

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

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

The response may also contain the following.

### **Role**

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).

### Example API Response XML Package

Below is an example of an API response XML package.

```markup
<SmarterU>
   <Result>Success</Result>
   <Info>
      <Role><![CDATA[Manufacturing Floor Manager]]></Role>
      <RoleID><![CDATA[LP-1324]]></RoleID>
   </Info>

   <Errors>
   </Errors>
</SmarterU>
```

## **Error Codes**

| Error Code | Message |
| --- | --- |
| CR:01 | The name provided is not valid. |
| CR:02 | The status provided is not valid. |
| CR:03 | The description provided is not valid. |
| CR:04 | The certification name provided is not valid. |
| CR:05 | The mandate level provided is not valid. |
| CR:06 | The required permissions are not met to call the createRole method. |
| CR:07 | One or more of the certification names provided are not valid. |
| CR:08 | One or more mandate levels provided are not valid. Acceptable values are *Mandatory*, *Optional*, or *Recommended*. |
| CR:09 | The status provided is not valid. Acceptable values are *Active* or *Inactive*. |
| CR:10 | Learning plan name cannot be used. |
| CR:11 | One or more certifications provided are not valid. Certifications cannot be added more than once. |
| CR:12 | Learning plan ID cannot be used. |
| CR:13 | The learning plan ID provided is not valid. |

## Related

- [Adding an Advanced Learning Plan](/adding-an-advanced-learning-plan.md)
- [API: getRole](/api-getrole.md)
- [API: listRoles](/api-listroles.md)
- [API: updateRole](/api-updaterole.md)
- [Assigning Certifications to a Learning Plan](/assigning-certifications-to-a-learning-plan.md)
- [Certifications](/certifications.md)
- [Learning Plan Automation](/learning-plan-automation.md)
- [Learning Plans](/learning-plans.md)