User

User Object

Field	Type	Description
id	snowflake	the user's id
first_name	string	the user's first name
last_name	string	the user's last name
email	string	the user's e-mail
phone_number	string	the user's mobile phone number
position	string	the user's position at their company
company	string	the user's company
avatar_hash	string	hash of the user's avatar file
roles	array<role>	list of roles assigned to the user
organisations	array<organisation>	list of organisations the user is a member of (partial)
badges	integer	bitwise bitmap of user badges (see User Badges)

User Object (extended)

When returned with extended details, the user object includes additional fields:

Field	Type	Description
initials	string	the user's initials (max 6 characters)
language	string	the user's preferred language
timezone_code	string	the user's timezone code
allow_connections_from	integer	who can send connection requests (see Allow Request From)
allow_shares_from	integer	who can share documents (see Allow Request From)
email_notifications	boolean	whether email notifications are enabled
sms_notifications	boolean	whether SMS notifications are enabled
email_newsletter	boolean	whether email newsletter subscriptions are enabled
email_confirmed	boolean	whether the user's e-mail has been confirmed
phone_number_confirmed	boolean	whether the user's phone number has been confirmed
signature	string	the user's saved signature
totp_token	string	one-time password token for QR sign-in flow
is_bot	boolean	whether the user is a bot account

User Badges

Badge	Value	Description
Verified	bit 0	the user has been verified
Supporter	bit 1	the user is a supporter
Staff	bit 31	the user is staff

Allow Request From

Value	Description
0x00	no one can send requests
0x01	members of the same organisation can send requests
0x02	connections can send requests
0xFF	everyone can send requests

User Email Object

Field	Type	Description
id	snowflake	the email's id
user_id	snowflake	the id of the user who owns this email
email	string	the e-mail address
is_primary	boolean	whether this is the user's primary e-mail
is_verified	boolean	whether the e-mail has been verified

Add Email

POST /users/@me/emails

Adds a new e-mail address to the current user's account. Requires authentication. A verification notification will be sent to the new e-mail address. If the e-mail is already pending against the user's account, returns the existing pending user email object without creating a duplicate.

JSON Params

Field	Type	Description
email	string	the e-mail address to add (required)

Error Responses

Status Code	Description
400	Bad request (e-mail already linked with another account)
400	Bad request (invalid e-mail address)
401	Unauthorized (missing or invalid authentication token)
404	Not found (user does not exist)

Verify Email

POST /users/@me/emails/{email.id}/verify

Sends a verification notification to the specified e-mail address. Requires authentication. If the e-mail is already verified, returns OK without sending a new notification.

Error Responses

Status Code	Description
401	Unauthorized (missing or invalid authentication token)
404	Not found (user or e-mail does not exist)

Get Email

GET /users/@me/emails/{email.id}

Returns the user email object for the specified e-mail id belonging to the current user. Requires authentication.

Error Responses

Status Code	Description
401	Unauthorized (missing or invalid authentication token)
404	Not found (user or e-mail does not exist)

Update Email

PATCH /users/@me/emails/{email.id}

Updates the specified user email object. Requires authentication. If an email_token is provided and the e-mail is not yet verified, the token will be validated and the e-mail marked as verified. If the e-mail is verified and is_primary is set to true, the e-mail will become the user's primary e-mail.

JSON Params

Field	Type	Description
email_token	string?	the verification token for the e-mail address
is_primary	boolean?	whether to make this the user's primary e-mail (requires verified status)

Error Responses

Status Code	Description
400	Bad request (e-mail already linked with another account)
401	Unauthorized (missing or invalid authentication token)
404	Not found (user or e-mail does not exist)

Remove Email

DELETE /users/@me/emails/{email.id}

Removes the specified e-mail address from the current user's account. Cannot remove the primary e-mail or an e-mail that is routed for organisation notifications.

Error Responses

Status Code	Description
401	Unauthorized (missing or invalid authentication token)
404	Not found (user or e-mail does not exist)

List Emails

GET /users/@me/emails

Returns a list of user email objects for the current user. Requires authentication. Optionally filters by organisation to return only e-mails that comply with the organisation's domain restrictions.

Parameters

Field	Type	Description
organisation_id	ulong?	filter e-mails by organisation domain requirements

Error Responses

Status Code	Description
400	Bad request (organisation not found or user is not a member)
401	Unauthorized (missing or invalid authentication token)
404	Not found (user does not exist)

Set Organisation Notification Email

PATCH /users/@me/organisations/{organisation.id}/email

Sets the notification routing e-mail for the specified organisation. Requires authentication. The e-mail must be verified and, if the organisation restricts e-mail domains, must match an approved domain for the organisation.

JSON Params

Field	Type	Description
notification_email_id	ulong	the id of the verified e-mail to route notifications to (required)

Error Responses

Status Code	Description
400	Bad request (verified e-mail does not exist)
400	Bad request (e-mail domain forbidden by organisation)
401	Unauthorized (missing or invalid authentication token)
404	Not found (user or organisation does not exist)

Get Logged in User

GET /users/@me

Returns the user object for the logged in user. Requires a valid authentication token.

Error Responses

Status Code	Description
401	Unauthorized (missing or invalid authentication token)
404	Not found (user does not exist)

Get User

GET /users/{user.id}

Returns the user object for the given user id. Requires authentication. The user must be a member of an organisation that the requesting user also belongs to. The fields returned will depend on the user's relationship with the organisation.

Error Responses

Status Code	Description
400	Bad request (user not found in shared organisations)
401	Unauthorized (missing or invalid authentication token)

Delete User Account

DELETE /users/@me

Deletes the current user's account. Requires authentication. If no email_token is provided, an e-mail verification token will be sent to the user's registered e-mail address. The user must then call this endpoint again with the token to confirm deletion. The user must leave all organisations and not be an organisation owner before deletion.

JSON Params

Field	Type	Description
email_token	string?	the e-mail verification token for account deletion; if omitted, a token will be sent via e-mail

Error Responses

Status Code	Description
400	Bad request (code 0x01002: user is still a member of an organisation)
400	Bad request (code 0x01000: user is an organisation owner)
400	Bad request (code 0x01001: error verifying deletion token)
401	Unauthorized (missing or invalid authentication token)

Lookup User

GET /users/lookup

Looks up a user by e-mail address. Requires authentication. The user must have the MANAGE_FLEETS permission for at least one organisation that the looked-up user also belongs to (if allow_shares_from is set to Organisation). Returns the user object with mutual organisations.

Parameters

Field	Type	Description
email	string	the e-mail address to look up

Error Responses

Status Code	Description
400	Bad request (authenticated user not found)
403	Forbidden (no mutual organisations with required permissions)
404	Not found (user with e-mail not found)
401	Unauthorized (missing or invalid authentication token)

Get User Avatar

GET /users/avatar/{file_hash}

Returns the user's avatar image file. This endpoint does not require authentication. Supports optional image resizing via the size query parameter for JPEG and PNG images. Response is cached for 15 minutes.

Parameters

Field	Type	Description
size	integer?	the desired image size for resizing (applied to JPEG/PNG only)

Error Responses

Status Code	Description
404	Not found (user with avatar hash not found)

Verify Phone Number

POST /users/@me/verify-phone-number

Sends a verification code to the user's registered phone number via SMS. Requires authentication. If the phone number is already confirmed, returns OK without sending a new code.

Error Responses

Status Code	Description
401	Unauthorized (missing or invalid authentication token)
404	Not found (user does not exist)

Update Current User

PATCH /users/@me

Updates the current user's profile. Requires authentication. Supports both application/json and multipart/form-data content types. All fields are optional; only the fields provided will be updated. Returns the updated user object on success.

Parameters

Field	Type	Description
first_name	string?	the user's first name
last_name	string?	the user's last name
company	string?	the user's company
position	string?	the user's position at their company
phone_number	string?	the user's mobile phone number (resets confirmation if changed)
phone_number_token	string?	the phone number verification token
timezone_code	string?	the user's timezone code (must be a valid IANA timezone)
language	string?	the user's preferred language
avatar	file?	avatar image file (JPEG or PNG, minimum 640 x 480 pixels)
enable_email_notifications	boolean?	whether email notifications are enabled
enable_sms_notifications	boolean?	whether SMS notifications are enabled
enable_email_newsletter	boolean?	whether email newsletter subscriptions are enabled
signature	string?	the user's signature (must be valid SVG, starting with <svg and ending with </svg>)

Error Responses

Status Code	Description
400	Bad request (invalid timezone code)
400	Bad request (avatar must be JPEG or PNG)
400	Bad request (avatar must be at least 640 x 480)
400	Bad request (signature must be valid SVG format)
401	Unauthorized (missing or invalid authentication token)
404	Not found (user does not exist)

Leave Organisation

DELETE /users/@me/organisations/{organisation.id}

Removes the current user from the specified organisation. The user cannot leave an organisation they own. Returns OK if the user is already not a member of the organisation.

Error Responses

Status Code	Description
400	Bad request (user is the owner of the organisation)
404	Not found (user does not exist)

Get Logged in User's Organisations

GET /users/@me/organisations

Returns a list of organisation objects that the user is a member of. Requires authentication. Includes subscription and permission context for each organisation.

{
    "id": "1234",
    "name": "XMTA"
}

Error Responses

Status Code	Description
401	Unauthorized (missing or invalid authentication token)
404	Not found (user does not exist)

List Document Shares

GET /users/@me/document-shares

Returns a list of document share objects for the current user. Includes shares with a status of Accepted or less. Each share includes the document, organisation, and shared-by user.

List Work Items

GET /users/@me/work-items

Returns a list of work item objects for the current user. Supports OData filtering and query parameters. Includes schedule invitees and tracking information for each work item. Response headers include X-Total-Count and X-Status-Count.

Parameters

Field	Type	Description
organisation	ulong?	filter by organisation id
type	ulong?	filter by work item type id
work_item	ulong?	filter by work item id
document	ulong?	filter by document id
fleet	ulong?	filter by fleet id
asset_group	ulong?	filter by asset group id
include_assets	boolean?	whether to include asset details
project	ulong?	filter by project id
status	ulong?	filter by status id
open	string	filter by open status
closed	string	filter by closed status
location	ulong?	filter by location id
start_date	string	filter by start date
finish_date	string	filter by finish date

List Fleets

GET /users/@me/fleets

Returns a list of fleet objects shared with the current user. Only includes fleet shares where no organisation is specified and the share status is Accepted.

List Shares

GET /users/@me/shares

Returns a list of all share objects for the current user. Includes project shares, document shares, document collection shares, and fleet shares with a status of Accepted or less. Each share includes the organisation, shared object, and shared-by user.

List Fleet Shares

GET /users/@me/fleet-shares

Returns a list of fleet share objects for the current user. Includes shares with a status of Accepted or less. Each share includes the fleet, organisation, work item type, and shared-by user.

List Fleet Subscriptions

GET /users/@me/fleets/{id}/subscriptions

Returns a list of fleet subscription objects for the current user and the specified fleet. Each subscription includes location and work item type information.

Error Responses

Status Code	Description
404	Not found (fleet does not exist)

List Work Item Subscriptions

GET /users/@me/work-items/{id}/subscriptions

Returns a list of work item subscription objects for the current user and the specified work item.

Error Responses

Status Code	Description
404	Not found (work item does not exist)

Create QR Token

PUT /users/@me/qr/token

Registers or refreshes a TOTP token for QR code sign-in flow. Requires authentication. Tokens are valid for 24 hours and are automatically deleted after expiry. Uses upsert semantics (insert or update on duplicate).

JSON Params

Field	Type	Description
token	string	the TOTP token to register (required)

Error Responses

Status Code	Description
400	Bad request (token is null or empty)
401	Unauthorized (missing or invalid authentication token)

Scan QR

POST /users/@me/qr/scan

Not yet implemented.

Error Responses

Status Code	Description
501	Not implemented

Get Toolbox

GET /users/@me/toolboxes/{id}

Returns the toolbox object for the specified id, including sections, topics, and the current user's signing status. Requires either an invitation to a schedule with the toolbox or a valid TOTP token parameter. Includes a JWT signing token (valid for 30 minutes) for the browser-based signing flow.

Parameters

Field	Type	Description
token	string?	TOTP token for authentication (required if not invited to a schedule)

Error Responses

Status Code	Description
400	Bad request (not invited and no token provided)
404	Not found (toolbox not found or invalid TOTP token)

Sign Toolbox

POST /users/@me/toolboxes/{id}/sign

Signs the current user onto the specified toolbox. Requires either a valid JWT token (generated from the Get Toolbox endpoint) or an invitation to a schedule with the toolbox. If signing via schedule invitation, the invitee status is updated from CheckedIn to Attending. Returns a toolbox user response object on success.

JSON Params

Field	Type	Description
jwt	string?	the JWT signing token (required if not signing via schedule)
schedule_id	ulong?	the id of the work item schedule (if signing via invitation)
first_name	string?	the user's first name
last_name	string?	the user's last name
company	string?	the user's company
position	string?	the user's position
phone_number	string?	the user's phone number (included if matching confirmed number)

Error Responses

Status Code	Description
400	Bad request (not invited, not checked-in, or missing required data)
404	Not found (toolbox not found, schedule not found, JWT mismatch, or JWT expired)

Get Witness JWT

GET /users/@me/witness/{id}

Returns a JWT signing token for witnessing the specified object (document revision or work item). Requires a valid TOTP token parameter. The JWT is valid for 30 minutes and can be used with the Sign Witness endpoint.

Parameters

Field	Type	Description
token	string	TOTP token for authentication (required)

Error Responses

Status Code	Description
400	Bad request (token is null or empty)
404	Not found (object token not found, document/work item not found, or invalid TOTP token)

Sign Witness

POST /users/@me/witness/{id}/sign

Witnesses the specified object (document revision or work item). Requires a valid JWT token (generated from the Get Witness JWT endpoint). Creates a witness record with the user's details and signature. Returns a witness response object on success.

JSON Params

Field	Type	Description
jwt	string	the JWT signing token (required)
first_name	string?	the user's first name
last_name	string?	the user's last name
company	string?	the user's company
position	string?	the user's position
phone_number	string?	the user's phone number (included if matching confirmed number)

Error Responses

Status Code	Description
400	Bad request (missing JWT or invalid request)
404	Not found (object token not found, document/work item not found, JWT mismatch, or JWT expired)

List User Inductions

GET /users/@me/inductions

Returns a list of induction objects assigned to the current user that have not yet been completed (no valid induction record). Each induction includes the induction revision and any existing induction record.

Get User Induction

GET /users/@me/inductions/{id}

Returns the induction object for the specified id assigned to the current user. The induction must not have a valid (non-expired) induction record. Includes the induction revision and any existing induction record.

Error Responses

Status Code	Description
404	Not found (induction not found or already completed)