Skip to content

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)

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.

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"
}
}

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. null when not set, for example for a user who was invited but has not completed their account yet
  • last_name: Last name of the user. null when not set
  • deleted_at: ISO 8601 timestamp of the user’s removal from the company. null while the user is a member of at least one of the listed companies. Only set with include_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 ASSIGNEE when a ticket is assigned to the group, so it is resolved by the same id filter as a person.
  • name: Name of the user group. null when not set
  • users: The current members of the group, each with id, first_name and last_name as 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 own USER item when your filter includes their id.
  • deleted_at: ISO 8601 timestamp of the group’s removal from the company. null for a current group. Only set with include_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.

List all users and user groups:

Terminal window
curl -X GET "https://api.sitemark.com/users?_page=1&_pageSize=100" \
-H "Authorization: ApiKey your-api-key-here"

Resolve a single user ID:

Terminal window
curl -X GET "https://api.sitemark.com/users?id=42" \
-H "Authorization: ApiKey your-api-key-here"

Resolve several user IDs (with brackets):

Terminal window
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:

Terminal window
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:

Terminal window
curl -X GET "https://api.sitemark.com/users?_sortBy=%2Blast_name&_pageSize=100" \
-H "Authorization: ApiKey your-api-key-here"
{
"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
}
}
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.