Users
List Users
Section titled “List Users”Retrieves the users and user groups of the companies your API key can read. Use it to resolve a user id returned by another endpoint to a name: the ASSIGNEE of a ticket, which can be a person or a user group, the value of a USER field, or the user_id of a property change.
A property change gives its author as principal_id: resolve that id with List Principals, not with this endpoint. The user_id of a property change is also deprecated.
Only names are published. Email addresses, phone numbers and other personal details are never returned.
Endpoint: GET /users
Authentication: Required (API Key)
Query Parameters
Section titled “Query Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer[] | No | Filter by one or more user IDs. At most 200. Without it, every user and user group of the companies your API key can read is listed. |
include_deleted |
boolean | No | Also list the users and user groups that were removed from those companies. Defaults to false. |
_page |
integer | No | Page number (positive integer, defaults to 1) |
_pageSize |
integer | No | Number of users per page (positive integer, defaults to 10, max 10,000) |
_sortBy |
string | No | Sort order. Format: +field (ascending) or -field (descending); repeat the parameter for tie-breaks. Sortable fields: id, last_name. Default: -id (newest first) |
Note: in a URL a literal + decodes to a space, so an ascending _sortBy must be percent-encoded as %2B (_sortBy=%2Blast_name).
When sorting by last_name, in either direction, users without a last name come last. User groups have no last name, so they also come last.
Response Format
Section titled “Response Format”Returns a paginated response. Each item in data is either a person (type is USER) or a user group (type is GROUP), with a different shape for each:
{ "data": [ { "type": "USER", "id": "integer", "first_name": "string | null", "last_name": "string | null", "deleted_at": "string | null" }, { "type": "GROUP", "id": "integer", "name": "string | null", "users": [ { "id": "integer", "first_name": "string | null", "last_name": "string | null" } ], "deleted_at": "string | null" } ], "pagination": { "rowCount": "integer", "pageCount": "integer", "page": "integer", "pageSize": "integer" }}Response Fields
Section titled “Response Fields”Read type first to know which of the two shapes an item has.
Person (type is USER):
- type: Always
USER - id: Integer ID of the user
- first_name: First name of the user.
nullwhen not set, for example for a user who was invited but has not completed their account yet - last_name: Last name of the user.
nullwhen not set - deleted_at: ISO 8601 timestamp of the user’s removal from the company.
nullwhile the user is a member of at least one of the listed companies. Only set withinclude_deleted
User group (type is GROUP):
- type: Always
GROUP - id: Integer ID of the user group. This is the id that appears as a ticket
ASSIGNEEwhen a ticket is assigned to the group, so it is resolved by the sameidfilter as a person. - name: Name of the user group.
nullwhen not set - users: The current members of the group, each with
id,first_nameandlast_nameas for a person. Empty when the group has no members. Members are always people, never other groups. Every member is a current member of the group’s company, so they are also listed as their ownUSERitem when your filter includes their id. - deleted_at: ISO 8601 timestamp of the group’s removal from the company.
nullfor a current group. Only set withinclude_deleted. A removed group has no members.
pagination: The standard pagination object. rowCount counts only the users you are allowed to see.
Which users are listed: the current members and user groups of every company your API key can read. For a partner API key, that is the partner company and every company it manages. Users and user groups removed from a company are left out, unless you set include_deleted=true: then they are listed too, with the time of their latest removal in deleted_at. Use it to resolve the ids in older records, such as the assignee of a ticket or the author of a property change, to a name. Users and user groups removed before 17 November 2026 are not listed, even with include_deleted=true.
Example Requests
Section titled “Example Requests”List all users and user groups:
curl -X GET "https://api.sitemark.com/users?_page=1&_pageSize=100" \ -H "Authorization: ApiKey your-api-key-here"Resolve a single user ID:
curl -X GET "https://api.sitemark.com/users?id=42" \ -H "Authorization: ApiKey your-api-key-here"Resolve several user IDs (with brackets):
curl -g -X GET "https://api.sitemark.com/users?id[]=42&id[]=57&id[]=88" \ -H "Authorization: ApiKey your-api-key-here"Resolve a user ID that may belong to a removed user:
curl -X GET "https://api.sitemark.com/users?id=42&include_deleted=true" \ -H "Authorization: ApiKey your-api-key-here"Sort by last name, A to Z:
curl -X GET "https://api.sitemark.com/users?_sortBy=%2Blast_name&_pageSize=100" \ -H "Authorization: ApiKey your-api-key-here"Example Response
Section titled “Example Response”{ "data": [ { "type": "GROUP", "id": 88, "name": "Surveyors", "users": [ { "id": 61, "first_name": "Alan", "last_name": "Turing" }, { "id": 42, "first_name": "Ada", "last_name": "Lovelace" } ], "deleted_at": null }, { "type": "USER", "id": 61, "first_name": "Alan", "last_name": "Turing", "deleted_at": null }, { "type": "USER", "id": 57, "first_name": null, "last_name": null, "deleted_at": null }, { "type": "USER", "id": 42, "first_name": "Ada", "last_name": "Lovelace", "deleted_at": null } ], "pagination": { "rowCount": 4, "pageCount": 1, "page": 1, "pageSize": 10 }}Error Responses
Section titled “Error Responses”| Status Code | Description |
|---|---|
| 401 | Unauthorized - Invalid or missing API key |
| 400 | Bad Request - More than 200 ids, an invalid id, an unsortable _sortBy field, or an unsupported parameter. See Errors. |
| 429 | Too Many Requests - A rate limit was exceeded |
| 500 | Internal Server Error |
Note: Users you do not have access to are left out of the response; they do not cause an error. Naming such a user in id simply yields no row for it.