How do I get a list of my account's users from the External API?

Last updated: October 20, 2026

The External API has a read-only users directory. It is useful for App Builder apps, org charts and integrations that need to know who is on your account.

Endpoints

  • GET /users returns the users on your account.

  • GET /users/{userId} returns one user, whatever their status. You get a 404 if the ID is unknown.

Filter by status

GET /users returns active users by default. Add ?status=inactive or ?status=all to change that. Any other value is rejected with a validation error. The list is not paginated. It is sorted by first name, then last name.

Fields returned

Field

Meaning

id

User ID

name, first_name, last_name

The user's name

email

The user's email address. It is null if the API token was created with the restrict-PII option.

role

The user's main role

roles

Names of the user's permission groups

status

1 means active. Any other value means inactive.

last_login_at

Last login date and time

Passwords, one-time codes and API tokens are never returned.

Permissions

The API token's user needs the staff read permission. This is the same permission the in-app user directory needs to show emails. Without it, calls are refused.