Roles
A role is similar to an ordinary user. You can assign tasks to a role and use it in your workflows. Each role participant receives a task in their Inbox, and when at least one of them approves or declines the task, it is forwarded to the next stage.
You can find additional information about roles in the help section.
Methods
- GET/rolesGet all roles in the organization
- GET/roles/{id}Get a role details by ID
- POST/rolesCreate role
- PUT/roles/{role-id}Update role
- DELETE/roles/{role-id}Delete role
GET /roles
This method returns a list of roles in your organization.
GET https://api.pyrus.com/v4/roles
Response body
{
"roles": [
{
"id": 32568,
"name": "Accountant",
"banned": false,
"member_ids": [
1233,
1731,
2384
]
},
{
"id": 13355,
"name": "Managers",
"banned": false,
"member_ids": [
2384,
1346,
4444,
3460
]
}
]
}
curl
curl -X GET \ 'https://api.pyrus.com/v4/roles' \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
GET /roles/{id}
This method gives you a role details by ID.
GET https://api.pyrus.com/v4/roles/{id}
Response body
{
"id": 32568,
"name": "Accountant",
"banned": false,
"member_ids": [
1233,
1731,
2384
]
}
curl
curl -X GET \ 'https://api.pyrus.com/v4/roles/<ROLE_ID>' \ -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \ -H 'Content-Type: application/json'
POST /roles
This method creates a role in the user's organization.
POST https://api.pyrus.com/v4/roles
Request body
{
"name": "TechSupport",
"member_add": [
1732,
4487
]
}
Response body
{
"id": 9364,
"name": "TechSupport",
"banned": "false",
"member_ids": [
1732,
4487
]
}
curl
curl -X POST \
https://api.pyrus.com/v4/roles \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"name": "TechSupport",
"member_ids": [
1732,
4487
]
}'
Parameters
| name | Role name. |
| member_add | Role members. An array of person IDs. |
PUT /roles/{role-id}
This method updates a role.
PUT https://api.pyrus.com/v4/roles/9364
Request body
{
"name": "InternalTechSupport",
"member_add": [
3796
],
"member_remove": [
1732
],
"banned": false
}
Response body
{
"id": 9364,
"name": "InternalTechSupport",
"banned": "false",
"member_ids": [
3796,
4487
]
}
curl
curl -X PUT \
https://api.pyrus.com/v4/roles/9364 \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"name": "InternalTechSupport",
"member_add": [
3796
],
"member_remove": [
1732
],
"banned": false
}'
Parameters
| name | Role name. |
| member_add | Added role members. An array of person IDs. |
| member_remove | Removed role members. An array of person IDs. |
| banned | Ban/unban role. |
DELETE /roles/{role-id}
The method deletes a role from the user's organization.
DELETE https://api.pyrus.com/v4/roles/199829
Request body
{
"task_receiver_id": 12711
}
Response body
{
"id": 199829,
"name": "MyRole",
"banned": false,
"fired": true
}
curl
curl -X DELETE \
https://api.pyrus.com/v4/roles/199829\
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"task_receiver_id": 12711
}'
Parameters
task_receiver_id — the user be added to the task of deleting a role.