# Create a new role

Creates a new role with the specified name, description, and product-level module permissions. [0=Full-control; 1=Read-Write; 2=Read-Only; -1=No Access]

## Endpoint

**POST** `/emsapi/roles`

## Request

### Request URL

```text
https://{server-hostname}:8383/emsapi/roles
```

### Scope

```text
Admin.CREATE
```

### Header

```text
Authorization: d92d4xxxxxxxxxxxxx15f52
```

## Request Parameters

### Request Headers

- **accept** `string` **Mandatory**  
  `application/addRole.v1+json`

  Specifies the expected response format. Set to application/addRole.v1+json to receive the role creation response in JSON format.

- **content-type** `string` **Mandatory**  
  `application/addRole.v1+json`

  Specifies the request payload format. Set to application/addRole.v1+json to submit the role data in JSON format.

### Request Body

`application/json`

- `JSON object`
  - **roleName** `string` **Mandatory**

    Unique name for the new role. Supports alphanumeric characters, spaces, and special characters. Maximum 100 characters.

  - **roleDescription** `string` **Mandatory**

    Optional description of the role's purpose and access level. Maximum 250 characters.

  - **roleDetails** `JSON object` **Mandatory**

    Product-keyed object mapping each product name to its module and feature permission details for this role.

## Sample Request

```curl
curl --request POST \
  --url https://appdomain/emsapi/roles \
  --header 'Authorization:  d92d4xxxxxxxxxxxxx15f52' \
  --header 'accept: application/addRole.v1+json' \
  --header 'content-type: application/addRole.v1+json' \
  --data '{"roleName":"testrole","roleDetails":{"osd":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"OSD Imaging"}]},"desktopCentral":{"modules":[{"0":true,"1":true,"2":true,"-1":false,"moduleId":"97913000000010497","value":"Configurations"},{"0":false,"1":false,"2":false,"-1":true,"value":"Patch Management"},{"0":false,"1":false,"2":false,"-1":true,"value":"Vulnerability Mgmt"},{"0":false,"1":false,"2":false,"-1":true,"value":"Software Deployment"},{"0":false,"1":false,"2":false,"-1":true,"moduleId":"97913000000010506","value":"Inventory"}]},"mdm":{"modules":[{"0":false,"1":false,"2":false,"-1":true,"value":"MDM Enrollment"}]}},"roleDescription":"sadasd"}'
```

## Sample Request Body

Create role with full module structure across desktopCentral, osd, browserSecurity, SecurityAddOn, and mdm.

```json
{
  "roleName": "testrole",
  "roleDetails": {
    "osd": {
      "modules": [
        {
          "0": false,
          "1": false,
          "2": false,
          "-1": true,
          "value": "OSD Imaging"
        }
      ]
    },
    "desktopCentral": {
      "modules": [
        {
          "0": true,
          "1": true,
          "2": true,
          "-1": false,
          "moduleId": "97913000000010497",
          "value": "Configurations"
        },
        {
          "0": false,
          "1": false,
          "2": false,
          "-1": true,
          "value": "Patch Management"
        },
        {
          "0": false,
          "1": false,
          "2": false,
          "-1": true,
          "value": "Vulnerability Mgmt"
        },
        {
          "0": false,
          "1": false,
          "2": false,
          "-1": true,
          "value": "Software Deployment"
        },
        {
          "0": false,
          "1": false,
          "2": false,
          "-1": true,
          "moduleId": "97913000000010506",
          "value": "Inventory"
        }
      ]
    },
    "mdm": {
      "modules": [
        {
          "0": false,
          "1": false,
          "2": false,
          "-1": true,
          "value": "MDM Enrollment"
        }
      ]
    }
  },
  "roleDescription": "sadasd"
}
```

## Response Parameters

### HTTP Code 200

Response Body: `application/json`

- `JSON object`
  - **roleId** `string`

    Unique identifier assigned to the newly created role.

  - **roleName** `string`

    Name of the newly created role.

  - **message** `string`

    Success message confirming role creation.

  - **successCode** `string`

    Success code for the role creation operation.

### HTTP Code 412

Response Body: `application/json`

- `JSON object`
  - **errorCode** `string`

    Application-specific error code indicating the reason for the request failure.

  - **errorMsg** `string`

    Error message describing the cause of the error.

## Possible Response Codes

- **200** `HTTP code`
- **412** `HTTP code`

## Sample Response: HTTP 200

Role creation success response.

```json
{
  "roleId": "97913000000566015",
  "roleName": "Security Auditor",
  "message": "New role Security Auditor has been added successfully.",
  "successCode": "40015"
}
```

## Sample Response: HTTP 412

The Role Name already exists. Please choose a different name.

```json
{
  "errorCode": "40018",
  "errorMsg": "Role name Product Admin already exists."
}
```

![](https://www.zohowebstatic.com/sites/zweb/images/people/ico-help.png)

**Duration:** 1 minute | **Threshold:** 30 | **Lock period:** 5 minutes

Duration - Time window for the threshold.  
Threshold - Number of API calls allowed within the specified duration.  
Lock Period - Wait time before consecutive API requests.