API docsAppearance
Users
Endpoints
GET /v1/users
GET /v1/users/:id
GET /v1/users/:user_id/group_membershipsList users
GET /v1/usersReturns a page of users.
Parameters
| Name | Optional | Default | Description | Options |
|---|---|---|---|---|
| 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 summary objects.
Example responses
Success response (200)
json
{
"object": "array",
"has_more": true,
"next": "/v1/users?cursor=eyJzb3J0IjoiZW1haWwiLCJvcmRlciI6ImFzYyJ9",
"limit": 5,
"size": 5,
"data": [
{
"object": "user",
"id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe",
"company_role": "admin",
"urls": {
"group_memberships": "/v1/users/937ccbe2-4cb5-4c76-96bf-29510b514dfa/group_memberships"
}
},
{...},
{...},
{...},
{...}
]
}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 |
|---|---|
| 422 | Invalid request, supplied parameters did not pass validation. |
Retrieve a user
GET /v1/users/:idGets the details of a single user.
Parameters
| Name | Optional | Type | Description |
|---|---|---|---|
| id | required | string | The ID of the user to retrieve. |
Returns
A user object.
Example responses
Success response (200)
json
{
"object": "user",
"id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
"email": "jane@example.com",
"first_name": "Jane",
"last_name": "Doe",
"company_role": "admin",
"urls": {
"group_memberships": "/v1/users/937ccbe2-4cb5-4c76-96bf-29510b514dfa/group_memberships"
}
}Error response (404)
json
{
"error": "User not found"
}Errors
| Code | Description |
|---|---|
| 404 | User with the given ID was not found. |
User group memberships
List user group memberships
GET /v1/users/:user_id/group_membershipsReturns a page of user group memberships for a user.
Parameters
| Name | Optional | Default | Description | Options |
|---|---|---|---|---|
| user_id | required | The ID of the user whose group memberships to retrieve. | ||
| Pagination parameters | See pagination for more information. |
Returns
A page of user group membership objects.
Example responses
Success response (200)
json
{
"object": "array",
"has_more": true,
"next": "/v1/users/937ccbe2-4cb5-4c76-96bf-29510b514dfa/group_memberships?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
"limit": 5,
"size": 5,
"data": [
{
"object": "user_group_membership",
"id": "9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26",
"name": "Leadership",
"user_id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
"user_group_id": "9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26",
"urls": {
"user_group": "/v1/user_groups/9e5f0f70-6fa8-4f7e-b61f-4c11a7a0cf26"
}
},
{...},
{...},
{...},
{...}
]
}Error response (404)
json
{
"error": "User not found"
}Error response (422)
json
{
"error": {
"sort": ["must be one of"],
"order": ["must be one of"],
"limit": ["must be greater than 0"]
}
}Errors
| Code | Description |
|---|---|
| 404 | User with the given ID was not found. |
| 422 | Invalid request, supplied parameters did not pass validation. |