users.linkableAccounts.list

Search the accounts DX has imported from a source, and get the account IDs to pass to users.links.set, users.links.create, and users.links.delete.

Facts


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

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`source`	`Text`	The tool to search. See Sources.

Optional arguments

Name	Type	Description
`query`	`Text`	Case-insensitive text to find in the account’s name, email, or username. See Filters by source.
`external_id`	`Text`	Only return the account with this ID from the tool itself.
`instance_id`	`Text`	Only return accounts from this instance, organization, workspace, or connection, as returned in `instance_id`.
`linked`	`Boolean`	`true` returns only accounts linked to a DX user. `false` returns only unlinked accounts.
`page`	`Integer`	Page number to return. Defaults to `1`.
`page_size`	`Integer`	Number of accounts to return per page. Defaults to `100`, maximum `100`.

Usage info

This method requires DX Data Cloud.

Results are ordered by account ID. Accounts are listed separately even when they share a name or email, so check external_id, instance_id, and the profile fields to pick the right one.

Results exclude accounts that can’t be linked, such as GitHub bots and inactive GitHub accounts. If the source isn’t connected, the method returns an empty list.

Searches on large sources can return query_timeout. Add instance_id, external_id, or a longer query to narrow the search.

Filters by source

Each source supports a different set of filters. Passing a filter the source doesn’t support returns an error.

Source	`query` searches	`external_id`	`instance_id`
`ado`	name, username, email	Yes	Azure DevOps organization
`amazon_kiro`	email	Yes	No
`bitbucket`	name, email	Yes	Bitbucket workspace
`bitbucket_server`	name, email	Yes	Bitbucket Data Center connection
`claude_code`	name, email	Yes	No
`codex`	email	Yes	No
`cursor`	email	No	No
`github`	username	Yes	GitHub instance
`gitlab`	name, username	Yes	GitLab instance
`jira`	name, email	Yes	Jira instance
`linear`	name, email	Yes	No
`windsurf`	name, email	No	No

Example request

This is a typical request:

curl -sS -G "https://api.getdx.com/users.linkableAccounts.list" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -H "Accept: application/json" \
  --data-urlencode 'source=github' \
  --data-urlencode 'query=jane' \
  --data-urlencode 'linked=false'

Example response

This is a typical success response:

{
  "ok": true,
  "accounts": [
    {
      "id": "4812",
      "source": "github",
      "external_id": "58291034",
      "instance_id": "3",
      "name": null,
      "email": null,
      "username": "jane-smith",
      "linked_user_id": null,
      "label": "jane-smith"
    }
  ],
  "next_page": null,
  "total": 1,
  "total_pages": 1
}

Response fields

Field	Type	Description
`ok`	`Boolean`	Indicates whether the request succeeded.
`accounts`	`Array`	Matching accounts 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 accounts.
`total_pages`	`Integer`	Total number of available pages.

Each object in accounts includes the fields below. Fields the source doesn’t provide are null.

Field	Type	Description
`id`	`String`	Account ID to pass to the `users.links` methods.
`source`	`String`	Source the account comes from.
`external_id`	`String \| null`	ID the tool itself assigns to the account.
`instance_id`	`String \| null`	Instance, organization, workspace, or connection the account belongs to.
`name`	`String \| null`	Account name.
`email`	`String \| null`	Account email address.
`username`	`String \| null`	Account username.
`linked_user_id`	`String \| null`	ID of the DX user the account is linked to, or `null` when it isn’t linked.
`label`	`String`	The first of `username`, `name`, `email`, `external_id`, or `id` that is set.

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, or Data Cloud is not enabled for the account.
`not_authorized`	The bearer token does not include `users:read`.
`query_timeout`	Data Cloud did not respond in time. Narrow the search and retry.
`Invalid parameter: ...`	`source` is not supported, a filter is malformed or not supported for the source, or `page` or `page_size` is out of range.
`Missing required parameter: source`	`source` was not provided.