View all methods

users.update

Update user properties including start_date, github_username, and gitlab_username.

GitHub and GitLab username properties are matching inputs used to automatically link accounts. To link more than one account from the same source to a user, use the User linking page or Linked accounts tab, or users.links.set.

Facts

Method POST https://api.getdx.com/users.update
Required scope users:write

Arguments

Required arguments

Name Type Description
token Token Auth token passed as an HTTP header.
email Text The email of the user you want to update.

Optional arguments

Name Type Description
start_date Date Date formatted as YYYY-MM-DD
timezone Text The user’s timezone as a tz database name, such as America/Chicago
github_username Text The Github username of the user
additional_github_username Text Additional GitHub username
gitlab_username Text The Gitlab username of the user
ai_light_adoption_date Date Date formatted as YYYY-MM-DD
ai_moderate_adoption_date Date Date formatted as YYYY-MM-DD
ai_heavy_adoption_date Date Date formatted as YYYY-MM-DD
sso_email Text Alternate email used to authenticate through SAML SSO
additional_emails Array<Text> Additional email addresses for the user. Replaces any existing additional emails.
protected Boolean If set to TRUE, the user’s IC metrics will be de-identified. Learn more
exclude_from_snapshots Boolean If set to TRUE, the user will not be asked to participate in snapshots.
developer Boolean If set to TRUE, the user is a developer. If set to FALSE, the user is not. Pass null to clear the classification; this is only allowed for accounts that manage developer classification manually.

Usage info

This API method allows you to update your users’ properties within DX. Properties updated using this method will apply to the user in DX associated with the email you provide in the request payload.

Please note: User properties are different than custom user attributes.

Behaviors

This API method has the following behaviors:

  • DX will only update values for user properties based on what is passed into the request payload. This means for all optional arguments, if they are not included in the payload, those properties will not be modified for the user.
  • If you want to unset a text or date property, pass in a value of null for it.
  • Slack and Microsoft Teams keep user timezones in sync with DX, so timezone returns a 422 error instead of being saved when Slack or Teams would overwrite it. Accounts that use Slack always get this error. Accounts that use Teams get it once Teams has reported the user’s timezone.
  • When your account asks users in a snapshot whether they write code regularly, a user’s answer replaces the developer value you set. To keep developer under API control while running snapshots, ask your DX contact to turn on manual developer classification for your account.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/users.update \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@company.com",
    "start_date": "2024-10-07",
    "github_username": "my_github_username",
    "gitlab_username": "my_gitlab_username"
  }'

Example response

This is a typical success response:

{
  "ok": true,
  "user": {
    "email": "user@company.com",
    "start_date": "2024-10-07",
    "github_username": "my_github_username",
    "gitlab_username": "my_gitlab_username"
  }
}

Unsetting values

To unset a user property, pass null as the value. This will remove the property from the user.

Example request

curl -X POST https://api.getdx.com/users.update \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@company.com",
    "start_date": "2024-10-07",
    "github_username": null
  }'

Example response

{
  "ok": true,
  "user": {
    "email": "user@company.com",
    "start_date": "2024-10-07",
    "github_username": null
  }
}

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.
invalid_auth Some aspect of authentication cannot be validated.