View all methods

users.list

List users in your account with profile fields, custom attributes, and roles.

Facts

Method	GET https://api.getdx.com/users.list
Required scope	users:read

Arguments

Required arguments

Name	Type	Description
token	Token	Auth token passed as an HTTP header.

Optional arguments

Name	Type	Description
page	Integer	Page number to return. Defaults to 1.
page_size	Integer	Number of users to return per page. Defaults to 100, maximum 100.

Usage info

DX returns users in the platform who have at least one of the following:

• role
• a non-default user property
• member or manager of a team
• member of a group
• owner of an entity

Example request

This is a typical request:

curl -sS -G "https://api.getdx.com/users.list" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -H "Accept: application/json" \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=50'

Example response

This is a typical success response:

{
  "ok": true,
  "users": [
    {
      "id": "NTEyMDUw",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "github_username": "jane-smith",
      "gitlab_username": "jane.smith",
      "additional_github_username": "jane-smith-alt",
      "attributes": [
        {
          "name": "Level",
          "value": "Senior Engineer"
        }
      ],
      "deleted_at": null,
      "roles": []
    }
  ],
  "next_page": 2,
  "total": 125,
  "total_pages": 3
}

Response fields

Field	Type	Description
ok	Boolean	Indicates whether the request succeeded.
users	Array	List of users in the requested page.
next_page	Integer | null	Next page number, or null when there are no more results.
total	Integer	Total number of matching users.
total_pages	Integer	Total number of available pages.

Each object in users includes:

Field	Type	Description
id	String	User ID.
name	String	User display name.
email	String	User email address.
github_username	String | null	User GitHub username.
gitlab_username	String | null	User GitLab username.
additional_github_username	String | null	Additional GitHub username.
attributes	Array	Custom attributes for the user, including privileged.
deleted_at	String | null	Timestamp for soft-deleted users.
roles	Array	Assigned DX roles with role name and description.

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error	Description
not_authed	No authentication token provided.
not_authorized	The bearer token does not include users:read.