Read roles with a manage key
List your hub's roles and read one role's permissions, so your software can put people on cases with the right role.
In this article4 sections
This page covers reading your hub's rolesRole A set of permissions that decides what someone can see and do on a case, such as staff or clients., whose IDs you send when you put someone on a case. Paths are under https://prd-api-manage.caseactive.com/v1/<hub id>. A key can read roles but not create, change or delete them.
Calls
| Call | What it does |
|---|---|
GET /roles | Lists your hub's roles |
GET /roles/<role_id> | Reads one role, with its permissions |
GET /roles takes limit (default 20) and start_key, the startKey from the previous page. A hub has 20 roles at most, so one call with limit=20 gets them all.
Role IDs
A role's ID is role:: and its name, such as role::senior-paralegal. Every hub has three built-in roles:
| Role ID | Who it's for |
|---|---|
role::clients | Clients |
role::staff | Your team |
role::bots | Your hub's Virtual AssistantVirtual Assistant An automated team member that posts welcome messages, check-ins and stage updates for the firm; its posts carry a Virtual Assistant badge., which every API key acts as. Don't give it to anyone. |
What a role holds
GET /roles answers each role's role_id, name, role_type (system for the three built-in roles, custom for yours), description, color and users_ct, the number of places it holds on cases.
{
"data": {
"items": [
{"role_id": "role::clients", "name": "clients", "role_type": "system", "color": "#10B981", "users_ct": 214},
{"role_id": "role::senior-paralegal", "name": "senior-paralegal", "role_type": "custom", "description": "Paralegals who run intake", "color": "#6366F1", "users_ct": 9}
],
"currentItemCount": 2,
"selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/roles"
}
}
GET /roles/<role_id> adds:
| Field | What it holds |
|---|---|
permissions | What the role can do on a case, by section: case, convos, events, posts, forms, signs, invoices, notes, tasks and team. Each section lists names such as list_posts (see them), put_post (add or edit their own), delete_post, put_comment and moderator (manage everyone's). |
case_read_fields, case_write_fields | The case details the role sees, and the ones it may change |
user_read_fields, user_write_fields | The profile details of others on the case the role sees, and may change |
file_size | The largest file the role may upload, in MB, by kind: audios, docs, files, images, schemas and videos |
By default, role::staff and role::bots can manage everything on a case. role::clients can see the case and every section but notes, post and comment, add their own events, forms, e-signs and tasks, and pay invoices. Your hub may have changed them. For what each permission allows, see Look up every role permission.
If a call is refused
| Status | message | Why |
|---|---|---|
| 404 | ItemNotFoundException | Your hub has no role with that ID |
| 403 | BotNotAllowedException | You tried to create, change or delete a role |