Account user role assignment

This topic discusses how to work with user roles on an account.

Overview of account user role assignment

In the context of an account, a role (such as Underwriter) can be assigned to a user and group (such as Alice Applegate from the Los Angeles Branch UW group). The roles that can be assigned are defined in the UserRoles typelist.

Some account role assignment occurs automatically. For example, the Creator role is assigned automatically to the user who creates an account. Account user roles can also be assigned manually.

A single user can have multiple roles on an account. However, a single account role cannot be held by more than one user.

In Cloud API, account user roles are managed through a roles array. Every member of the array has the following structure:

"roles": [
  {
      "group": "<groupId>",
      "role": {
          "code": "<UserRolesCode>",
          "name": "<UserRolesName>"
      },
      "user": "<userId>"
  },
Java

For example, the following roles array identifies Alice Applegate (pc:8) from the Los Angeles Branch UW group (pc:55) as the Creator and Underwriter for the account.

"roles": [
    {
        "group": "pc:55",
        "role": {
          "code": "Creator",
          "name": "Creator"
        },
        "user": "pc:8"
    },
    {
        "group": "pc:55",
        "role": {
            "code": "Underwriter",
            "name": "Underwriter"
        },
        "user": "pc:8"
    }
  ]
Java

Retrieving account user roles

Use the following endpoint to retrieve a list of user role assignments for an account:

  • GET /account/v1/accounts/{accountId}/user-roles

Here's an example:

Command

GET /account/v1/accounts/pc:9/user-roles
Java

Response

{
  "data": {
    "attributes": {
      "roles": [
        {
          "group": "pc:55",
          "role": {
            "code": "Creator",
            "name": "Creator"
          },
          "user": "pc:8"
        },

        …
      ]
    }
  }
}
Java

Assigning account user roles

Use the following endpoint to assign an account role to a user on a given account:

  • POST /account/v1/accounts/{accountId}/user-roles/assign

The request body must specify the user, group, and role. Each call consists of one role being assigned to a group and user. If that role was already assigned to another user for the account, it is reassigned to the specified user.

For example, the following assigns the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:1117) on account pc:9.

Command

POST /account/v1/accounts/pc:9/user-roles/assign
Java

Request

{
    "data": {
        "attributes": {
          "group": "pc:1117",
          "role": {
            "code": "Auditor"
          },
          "user": "pc:220"
        }
    }
}
Java

Updating account user roles

Use the following endpoint to update the role assignment for an account:

  • PATCH /account/v1/accounts/{accountId}/user-roles

You can use the PATCH endpoint to add or remove multiple role assignments in one call.

PATCHes in Cloud API are destructive, not additive. When you PATCH the roles array, the new content replaces the previous content entirely.

If you want to only add user role assignments to an account, the PATCH must contain all current members of the roles array as well as the new one.

  • To add multiple role assignments or reassignments, add multiple new entries to the roles array.
  • To remove role assignments, omit those entries from the roles array.
  • If there are assignments you do not want to change, you must also include those assignments in the roles array.

For example, suppose account pc:9 has already assigned the roles of Creator and Underwriter to Alice Applegate (pc:8) from the Los Angeles Branch UW group (pc:55) and the role of Customer Rep to Chris Clark (pc:303) from the Los Angeles Branch UW group (pc:55). The following PATCH performs these actions:

  • Adds the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:1117).
  • Unassigns the role of Customer Rep. (This is done by omitting it from the roles array.)
  • Makes no changes to the Creator or Underwriter roles. (They are included in the roles array with their original data.)

Command

PATCH /account/v1/accounts/pc:9/user-roles
Java

Request

{
    "data": {
        "attributes": {
          "group": "pc:1117",
          "role": {
            "code": "Auditor"
          },
          "user": "pc:220"
        },
        {
          "group": "pc:55",
          "role": {
            "code": "Creator"
          },
          "user": "pc:8"
        },
        {
          "group": "pc:55",
          "role": {
            "code": "Underwriter"
          },
          "user": "pc:8"
        }
    }
}
Java