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
nullfor it. - Slack and Microsoft Teams keep user timezones in sync with DX, so
timezonereturns a422error 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
developervalue you set. To keepdeveloperunder 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. |