Roles represent standard sets of permissions available to your firm. Use the Roles API to view your firm's roles, and add or remove the users assigned to each role.

3104
Base Route/v1/roles
EndpointsGET
/v1/roles/:id
/v1/roles
/v1/roles/:id/relationships/assigned_users
/v1/roles/:id/assigned_users

POST
/v1/roles/:id/relationships/assigned_users

PATCH
/v1/roles/:id/relationships/assigned_users

DELETE
/v1/roles/:id/relationships/assigned_users
ProducesJSON
PaginationYes
Application Permissions Required"API Access: Create, edit, and delete"

"Manage firm settings: Users and permissions" for all operations.
OAuth ScopesGET
USERS and USERS_WRITE

POST, PATCH, and DELETE
USERS_WRITE

Resource Overview

The attributes below will always appear in GET, POST, and PATCH responses.

AttributeDescriptionExample
nameThe name of the role. String."Platform Team"

Relationships

RelationshipDescription
assigned_usersUsers assigned to the role.
"relationships":{
  "assigned_users":{
    "links":{
      "self":"/v1/roles/455914/relationships/assigned_users",
      "related":"/v1/roles/455914/assigned_users"
    },
    "data":[
      {
        "type":"users",
        "id":"621500"
      }
    ]
  }
}

📘

Note

Creation, deletion, and modification of roles are done from within the application. Roles must be created in the application before the API can be used to update its members.

Get a Role

Returns the details for a specific role.

GET /v1/roles/:id

Example:

GET https://examplefirm.addepar.com/api/v1/roles/80
HTTP/1.1 200
            
{
    "data": {
        "id": "80",
        "type": "roles",
        "attributes": {
            "name": "Advisor Role”
        },
        "relationships": {
            "assigned_users": {
                "links": {
                    "self": "/v1/roles/80/relationships/assigned_users",
                    "related": "/v1/roles/80/assigned_users"
                },
                "data": [
                    { 
                    "type": "users",
                    "id": "101"
                    }
                ]
            }
        },
        "links": {
            "self": "/v1/roles/80"
        }
}

Responses

  • 200 OK: Success
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not found: No role exists with the provided ID in the firm

Get All Roles

Returns a list of all roles at the firm.

GET /v1/roles

Example:

GET https://examplefirm.addepar.com/api/v1/roles
HTTP/1.1 200
            
{
    "data": {
        "id": "80",
        "type": "roles",
        "attributes": {
            "name": "Advisor Role”
        },
        "relationships": {
            "assigned_users": {
                "links": {
                    "self": "/v1/roles/80/relationships/assigned_users",
                    "related": "/v1/roles/80/assigned_users"
                },
                "data": [
                    { 
                    "type": "users",
                    "id": "101"
                    }
                ]
            }
        },
        "links": {
            "self": "/v1/roles/80"
        }
    },
    "data": {
        "id": "90",
        "type": "roles",
        "attributes": {
            "name": "Administrator Role”
        },
        "relationships": {
            "assigned_users": {
                "links": {
                    "self": "/v1/roles/90/relationships/assigned_users",
                    "related": "/v1/roles/90/assigned_users"
                },
                "data": [
                    {
                        "type": "users",
                        "id": "102"
                    }
                ]
            }
        },
            "links": {
                "self": "/v1/roles/90"
            }
      }
}

Response Codes:

  • 200 OK: Success
  • 403 Forbidden: User lacks sufficient application permissions

Get a Role's Users

Returns a list of IDs for all users assigned to a specific role.

GET /v1/roles/:id/relationships/assigned_users

Example:

GET https://examplefirm.com.addepar.com/api/v1/roles/80/relationships/assigned_users
HTTP/1.1 200
            
{
    "data": [
        {
        "id": "2000",
        "type": "users"
        }
    ]
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid relationship queried
  • 400 Bad Request: Include parameter not supported
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned role ID

Get a Role's User Details

Returns details about the users assigned to a specific role.

GET /v1/roles/:id/assigned_users

Example:

GET https://examplefirm.addepar.com/api/v1/roles/80/assigned_users
HTTP/1.1 200
            
{
      "id": "2000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": false,
        "external_user_id": "A67890"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_entities",
            "related": "/v1/users/2000/permissioned_entities"
          },
          "data": [
            {
               "type": "entities",
               "id": 10000
            },
            {
               "type": "entities",
               "id": 10001
            }
          ]
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/2000/relationships/assigned_role",
            "related": "/v1/users/2000/assigned_role"
          },
          "data": [
              {
              "type": "roles",
              "id": "80"
              }
          ]
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/2000/relationships/permissioned_groups",
            "related": "/v1/users/2000/permissioned_groups"
          },
          "data": [
            {
               "type": "entities",
               "id": 20000
            },
            {
               "type": "entities",
               "id": 20001
            }
          ]
        }
      },
      "links": {
        "self": "/v1/users/2000"
      }
    }
  ],
  "links": {
    "next": null
  }
}

Response Codes:

  • 200 OK: Success
  • 400 Bad Request: Invalid relationship queried
  • 400 Bad Request: Include parameter not supported
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not Found: Nonexistent/non-permissioned role ID

Assign Users to a Role

If a user is already assigned to a role, calling this endpoint will overwrite the role, and assign the user a new role.

POST /v1/roles/:id/relationships/assigned_users

Example:

POST https://examplefirm.addepar.com/api/v1/roles/90/relationships/assigned_users
            
{
    "data": [
        {
        "id": "2000",
        "type": "users"
        }
    ]
}
HTTP/1.1 204

Response Codes:

  • 204 No Content: Success
  • 400 Bad Request: Nonexistent/non-permissioned user/attribute ID
  • 404 Not Found: Nonexistent/non-permissioned role ID

Update Users Assigned to a Role

Updates the specified users assigned to a role.

PATCH /v1/roles/:id/relationships/assigned_users

Example:

PATCH https://examplefirm.addepar.com/api/v1/roles/80/relationships/assigned_users
            
{
    "data": [
        {
        "id": "2000",
        "type": "users"
        }
    ]
}
HTTP/1.1 204

Response Codes:

  • 204 No Content: Success
  • 400 Bad Request: Nonexistent/non-permissioned user/attribute ID
  • 404 Not Found: Nonexistent/non-permissioned user ID

Remove Users from a Role

Removes a specified user from a role.

DELETE /v1/roles/:id/relationships/assigned_users

Example:

DELETE https://examplefirm.addepar.com/api/v1/roles/80/relationships/assigned_users
            
{
    "data": [
        {
        "id": "2000",
        "type": "users"
        }
    ]
}
HTTP/1.1 204

Responses:

  • 204 No Content: Success
  • 400 Bad Request: Failed to provide an id or tried to delete a role that cannot be deleted
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not found: No role exists with the provided id in the firm

What’s Next