Skip to content

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)

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

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

Read type first to know which object an item has.

  • id: Integer ID of the principal. This is the principal_id of a property change.
  • type: USER, GROUP or API_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. null while the principal is a member of at least one of those companies. A revoked API key stays a member: revoking a key does not set deleted_at.

User (type is USER):

  • user.id: Integer ID of the user. This is the id that v1 USER and ASSIGNEE property values hold for a user, and the user_id of a property change.
  • user.first_name, user.last_name: Name of the user. null when 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 ASSIGNEE or USER property value: use group.legacy_user_id for a v1 value and id for a v2 value.
  • group.legacy_user_id: Integer ID that v1 ASSIGNEE and USER property values hold for this group. List Users returns it as the id of the group. null for 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.

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.

  1. List the principals. Get all pages; set _pageSize up to 10,000.
  2. For a v2 value, find the item whose id is equal to principal_id. You can also send these ids in the id filter.
  3. For a v1 value, find the USER item whose user.id is equal to the value, or the GROUP item whose group.legacy_user_id is equal to the value. You cannot filter on these ids.
  4. When deleted_at of 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.

List all principals:

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

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

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

List only the API keys:

Terminal window
curl -X GET "https://api.sitemark.com/principals?type=API_KEY" \
-H "Authorization: ApiKey your-api-key-here"
{
"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
}
}
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.