Users

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 user_id of a property change, or the ASSIGNEE of a ticket, which can be a person or a user group.

Only names are published. Email addresses, phone numbers and other personal details are never returned.

Endpoint: GET /users

Authentication: Required (API Key)

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.
`_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

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"
        },
        {
            "type": "GROUP",
            "id": "integer",
            "name": "string | null",
            "users": [
                {
                    "id": "integer",
                    "first_name": "string | null",
                    "last_name": "string | null"
                }
            ]
        }
    ],
    "pagination": {
        "rowCount": "integer",
        "pageCount": "integer",
        "page": "integer",
        "pageSize": "integer"
    }
}

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. 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

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.

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. Deleted users and users who have left the company are not listed.

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"

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

{
    "data": [
        {
            "type": "GROUP",
            "id": 88,
            "name": "Surveyors",
            "users": [
                {
                    "id": 61,
                    "first_name": "Alan",
                    "last_name": "Turing"
                },
                {
                    "id": 42,
                    "first_name": "Ada",
                    "last_name": "Lovelace"
                }
            ]
        },
        {
            "type": "USER",
            "id": 61,
            "first_name": "Alan",
            "last_name": "Turing"
        },
        {
            "type": "USER",
            "id": 57,
            "first_name": null,
            "last_name": null
        },
        {
            "type": "USER",
            "id": 42,
            "first_name": "Ada",
            "last_name": "Lovelace"
        }
    ],
    "pagination": {
        "rowCount": 4,
        "pageCount": 1,
        "page": 1,
        "pageSize": 10
    }
}

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
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.