User accounts

Account type, lifecycle status, and invite, join, and last-seen timestamps for your billable users. Administrator-only.

Working with an AI agent?or point it at the User accounts markdown or the full-API markdown.

List user accounts

GET

/api/v1/users

Account state for your billable users: type, lifecycle status, and invite/join/last-seen timestamps. Requires user:read, which only an Administrator or Owner can grant, because members cannot see this in the app. Unlike /api/v1/profiles this is NOT filtered to active people, which is what makes attrition analysis possible.

Parameter	Type	Description
cursor	string optional	Opaque cursor from a previous response's "nextCursor". Omit for the first page.
limit	number optional	Rows per page, 1-500. Defaults to 100.
updatedSince	string optional	ISO 8601 timestamp (or epoch milliseconds). Returns only accounts changed since this time. Departures appear here as an accountStatus change, with the row retained.
accountStatus	string optional	Comma-separated statuses to filter by. Any of: Pending, Active, Suspended, Inactive, Requested, PendingUpgrade. Defaults to all.
accountType	string optional	Comma-separated types to filter by. Any of: Member, Administrator, Owner, ServiceAccount. Defaults to all.

Response:

{
  data: {
    id: number;         // profiles.userId joins to this
    uuid: string;       // same identifier SCIM uses for its resource id
    email: string;
    accountType: Member | Administrator | Owner | ServiceAccount;
    accountStatus: Pending | Active | Suspended | Inactive | Requested | PendingUpgrade;
    invited: string | null;   // ISO 8601
    joined: string | null;    // ACCOUNT creation, ISO 8601. Not employment start.
    lastSeen: string | null;  // ISO 8601
    updated: string | null;   // ISO 8601
  }[];
  nextCursor: string | null;
  hasMore: boolean;
  syncedThrough: string;    // ISO 8601; pass back as updatedSince
}

Create or update a user account

POST

/api/v1/users/upsert

Create a user account, or update an existing one matched by email. Requires user:write, which only an Administrator or Owner can grant. An API token cannot change an Owner: a promotion to Owner, a demotion from Owner, and a new Owner answer 403. A person does it in Settings, with a sign-in of the last 15 minutes.

Parameter	Type	Description
email	string required	The email of the user.
firstName	string optional	The first name of the user.
lastName	string optional	The last name of the user.
displayName	string optional	The display name of the user.
accountType	Member \| Administrator \| Owner \| ServiceAccount optional	The account type of the user.
accountStatus	Pending \| Active \| Suspended \| Inactive \| Requested \| PendingUpgrade optional	The account status of the user.

Response:

{
  id: number;
  email: string;
  accountType: Member | Administrator | Owner | ServiceAccount;
  accountStatus: Pending | Active | Suspended | Inactive | Requested | PendingUpgrade;
  invited: string | null;
  joined: string | null;
}