Principals
List Principals
Section titled “List Principals”Retrieves the principals of the companies your API key can read. A principal is a user, a user group or an API key. Today only users and API keys are the authors of changes. Use this endpoint to resolve the principal_id of a property change to a type and a name. Use it also to resolve ASSIGNEE and USER property values: see Resolve ASSIGNEE and USER values.
A principal id is not a user id. A v1 ASSIGNEE or USER value (a number) holds a user or group id, not a principal id: do not send it in the id filter. A v2 value holds a principal id.
Email addresses, API key dates and revocations are never returned.
Endpoint: GET /principals
Authentication: Required (API Key)
Query Parameters
Section titled “Query Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer[] | No | Filter by one or more principal IDs. At most 200. Without it, every principal of the companies your API key can read is listed. |
type |
string[] | No | Filter by one or more types: USER, GROUP, API_KEY. Another value returns 400. |
_page |
integer | No | Page number (positive integer, defaults to 1) |
_pageSize |
integer | No | Number of principals per page (positive integer, defaults to 10, max 10,000) |
_sortBy |
string | No | Sort order. Format: +field (ascending) or -field (descending). Sortable fields: id. 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=%2Bid).
Response Format
Section titled “Response Format”Returns a paginated response. Each item has an id, a type and a deleted_at. The data of the type is in one object named for the type (user, group or api_key). Only the object of the item’s type is present:
{ "data": [ { "id": "integer", "type": "USER", "deleted_at": "timestamp | null", "user": { "id": "integer", "first_name": "string | null", "last_name": "string | null" } }, { "id": "integer", "type": "GROUP", "deleted_at": "timestamp | null", "group": { "id": "integer", "legacy_user_id": "integer | null", "name": "string", "members": "integer[]" } }, { "id": "integer", "type": "API_KEY", "deleted_at": "timestamp | null", "api_key": { "id": "uuid", "name": "string" } } ], "pagination": { "rowCount": "integer", "pageCount": "integer", "page": "integer", "pageSize": "integer" }}Response Fields
Section titled “Response Fields”Read type first to know which object an item has.
- id: Integer ID of the principal. This is the
principal_idof a property change. - type:
USER,GROUPorAPI_KEY. More types can be added; see Types. - deleted_at: ISO 8601 timestamp of the latest removal of the principal from the companies your API key can read.
nullwhile the principal is a member of at least one of those companies. A revoked API key stays a member: revoking a key does not setdeleted_at.
User (type is USER):
- user.id: Integer ID of the user. This is the id that v1
USERandASSIGNEEproperty values hold for a user, and theuser_idof a property change. - user.first_name, user.last_name: Name of the user.
nullwhen empty, for example for a user who was invited but has not completed their account yet.
User group (type is GROUP):
- group.id: Integer ID of the group itself. It does not match an
ASSIGNEEorUSERproperty value: usegroup.legacy_user_idfor a v1 value andidfor a v2 value. - group.legacy_user_id: Integer ID that v1
ASSIGNEEandUSERproperty values hold for this group. List Users returns it as theidof the group.nullfor a group that has no such id. Such a group cannot be assigned yet. - group.name: Name of the group.
- group.members: Principal IDs of the current members of the group, by principal ID, descending. Resolve them with this endpoint. A user whose account was deleted is left out. A member removed from the group’s company is not listed, and a removed group lists no members. Today every member is a user.
API key (type is API_KEY):
- api_key.id: UUID of the API key.
- api_key.name: Name of the API key. A revoked API key is also listed.
pagination: The standard pagination object. rowCount counts only the principals you are allowed to see.
Which principals are listed: the users, user groups and API keys of every company your API key can read, also the ones removed from it, with the time of their latest removal in deleted_at. So the author of an older property change still gets a name. For a partner API key, that is the partner company and every company it manages. To get only the current members, keep the items whose deleted_at is null. Users and user groups removed before 17 November 2026 are not listed. A deleted user account is not listed.
A principal_id of a property change can have no row here: the change was made by a principal of a company your API key cannot read (for example a Sitemark employee, or a member of a partner company), or by one removed before 17 November 2026. Show such an author as unknown.
Resolve ASSIGNEE and USER values
Section titled “Resolve ASSIGNEE and USER values”An ASSIGNEE or USER property value has one of two shapes:
| Shape | Example | Holds |
|---|---|---|
| v1 | 1042 |
A user id, or the legacy_user_id of a group. Not a principal id. |
| v2 | { "version": "2", "principal_id": 502 } |
The id of a principal. |
Sitemark stores a new value as v1 or v2, depending on the progress of its migration. Existing v1 values are not migrated: they stay v1. So your integration must read both shapes. v1 is not deprecated for reads.
Resolve both shapes with this endpoint, not with List Users: it cannot resolve a v2 value.
- List the principals. Get all pages; set
_pageSizeup to 10,000. - For a v2 value, find the item whose
idis equal toprincipal_id. You can also send these ids in theidfilter. - For a v1 value, find the
USERitem whoseuser.idis equal to the value, or theGROUPitem whosegroup.legacy_user_idis equal to the value. You cannot filter on these ids. - When
deleted_atof that item is set, the user or group was removed from the company. When no item matches, show the value as unknown.
A v2 value can name a principal of any type, so read type as described in Types.
Users and user groups removed before 17 November 2026 are not listed, so their values do not match.
Today a principal is a USER, a GROUP or an API_KEY. Sitemark plans to add more types. A new type is not a breaking change. Your integration must accept a type it does not know, for example skip the item or show it as unknown. It must not fail on it.
Example Requests
Section titled “Example Requests”List all principals:
curl -X GET "https://api.sitemark.com/principals?_page=1&_pageSize=100" \ -H "Authorization: ApiKey your-api-key-here"Resolve several principal IDs (with brackets):
curl -g -X GET "https://api.sitemark.com/principals?id[]=501&id[]=502&id[]=503" \ -H "Authorization: ApiKey your-api-key-here"List all principals to resolve ASSIGNEE and USER values:
curl -X GET "https://api.sitemark.com/principals?_page=1&_pageSize=10000" \ -H "Authorization: ApiKey your-api-key-here"List only the API keys:
curl -X GET "https://api.sitemark.com/principals?type=API_KEY" \ -H "Authorization: ApiKey your-api-key-here"Example Response
Section titled “Example Response”{ "data": [ { "id": 503, "type": "API_KEY", "deleted_at": null, "api_key": { "id": "0193c0b6-4c2d-7f1a-8b3e-5d6f7a8b9c0d", "name": "Work order sync" } }, { "id": 502, "type": "GROUP", "deleted_at": null, "group": { "id": 9, "legacy_user_id": 1042, "name": "Surveyors", "members": [501] } }, { "id": 501, "type": "USER", "deleted_at": null, "user": { "id": 42, "first_name": "Jane", "last_name": "Doe" } } ], "pagination": { "rowCount": 3, "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 unknown type, an unsortable _sortBy field, or an unsupported parameter (INVALID_REQUEST). See Errors. |
| 429 | Too Many Requests - A rate limit was exceeded |
| 500 | Internal Server Error |
Note: Principals you do not have access to are left out of the response; they do not cause an error. Naming such a principal in id simply yields no row for it.