API docsAppearance
User groups
Endpoints
GET /v1/user_groups
GET /v1/user_groups/:id
GET /v1/user_groups/:user_group_id/usersList user groups
GET /v1/user_groupsReturns a page of user groups.
Parameters
| Name | Optional | Default | Description | Options |
|---|---|---|---|---|
| Pagination parameters | See pagination for more information. | |||
| sort | optional | Sort field. | created_at, name, users_count | |
| order | optional | Sort order. | asc, desc | |
| limit | optional | 50 | Number of user groups per page. Must be between 1 and 100. |
Returns
A page of user group summary objects.
Example responses
Success response (200)
json
{
"object": "array",
"has_more": true,
"next": "/v1/user_groups?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiYXNjIn0",
"limit": 5,
"size": 5,
"data": [
{
"object": "user_group",
"id": "9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26",
"name": "Leadership",
"users_count": 3,
"owner": {
"id": "2b13c87c-f8e4-4a3c-97a5-bcc7f9f0be9f",
"name": "Olly Owner",
"email": "olly@example.com"
},
"urls": {
"details": "/v1/user_groups/9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26",
"users": "/v1/user_groups/9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26/users"
}
},
{...},
{...},
{...},
{...}
]
}Error response (422)
json
{
"error": {
"sort": ["must be one of: created_at, name, users_count"],
"order": ["must be one of: asc, desc"],
"limit": ["must be greater than 0"]
}
}Errors
| Code | Description |
|---|---|
| 422 | Invalid request, supplied parameters did not pass validation. |
Retrieve a user group
GET /v1/user_groups/:idGets the details of a single user group.
Parameters
| Name | Optional | Type | Description |
|---|---|---|---|
| id | required | string | The ID of the user group to retrieve. |
Returns
A user group object.
Example responses
Success response (200)
json
{
"object": "user_group",
"id": "9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26",
"name": "Leadership",
"users_count": 3,
"owner": {
"id": "2b13c87c-f8e4-4a3c-97a5-bcc7f9f0be9f",
"name": "Olly Owner",
"email": "olly@example.com"
},
"urls": {
"users": "/v1/user_groups/9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26/users"
}
}Error response (404)
json
{
"error": "User group not found"
}Errors
| Code | Description |
|---|---|
| 404 | User group with the given ID was not found. |
User group users
List users in a user group
GET /v1/user_groups/:user_group_id/usersReturns a page of users in the user group.
Parameters
| Name | Optional | Default | Description | Options |
|---|---|---|---|---|
| user_group_id | required | The ID of the user group whose users to retrieve. | ||
| Pagination parameters | See pagination for more information. | |||
| sort | optional | Sort field. | created_at, email, first_name, last_name | |
| order | optional | Sort order. | asc, desc | |
| limit | optional | 50 | Number of users per page. Must be between 1 and 100. |
Returns
A page of user objects. Each user includes id, first_name, last_name, email, company_role, and urls.details.
Example responses
Success response (200)
json
{
"object": "array",
"has_more": true,
"next": "/v1/user_groups/9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26/users?cursor=eyJzb3J0IjoiZW1haWwiLCJvcmRlciI6ImFzYyJ9",
"limit": 5,
"size": 5,
"data": [
{
"object": "user",
"id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
"email": "amy@example.com",
"first_name": "Amy",
"last_name": "Member",
"company_role": "admin",
"urls": {
"details": "/v1/users/937ccbe2-4cb5-4c76-96bf-29510b514dfa"
}
},
{...},
{...},
{...},
{...}
]
}Error response (404)
json
{
"error": "User group not found"
}Error response (422)
json
{
"error": {
"sort": ["must be one of: created_at, email, first_name, last_name"],
"order": ["must be one of: asc, desc"],
"limit": ["must be greater than 0"]
}
}Errors
| Code | Description |
|---|---|
| 404 | User group with the given ID was not found. |
| 422 | Invalid request, supplied parameters did not pass validation. |