The users API methods allow you to update a few simple user attributes as well as fetch the details of users who are relevant to DX.
API Methods
users.update
This API allows you to update the start_date, github_username, or gitlab_username of a given user based on their email address.
Required Arguments
Name | Description |
String - The email address of the user ID you want to update |
Optional Arguments
Name | Description |
start_date | Date - Formatted in YYYY-MM-DD |
github_username | String - The Github username of the user |
additional_github_username | String - Useful in the case that a user has an additional github username |
gitlab_username | String - The Gitlab username of the user |
curl -X POST https://api.getdx.com/users.update -H 'Authorization: Bearer <API_TOKEN_HERE>'
{
"email": "[email protected]",
"start_date": "2024-10-07", // optional
"github_username": "myuser" // optional
"gitlab_username": "myuser" // optional
}
users.listAttributable
This API allows you to retrieve details about the users in your organization. The concept of an "attributable" user means that they are relevant to DX in some way. If any one of the following is true, then a user will be considered "attributable":
They manage a team
They manage someone who belongs to a team
They belong to a team themselves
They’re an admin/observer/interviewer
They have a github/gitlab username
They have is_developer set to true (collected at the time of snapshot)
They have a
start_datesetThey have any amount of existing attributes assigned to them
Response
Name | Description |
users.id | ID - Formatted in YYYY-MM-DD |
users.name | String - The Github username of the user |
users.github_username | String - The Gitlab username of the user |
users.additional_github_username | String - The Github username of the user |
users.gitlab_username | String - The Github username of the user |
users.developer | Boolean - Whether or not the user is considered someone who 'writes code regularly' |
users.tags | Array - List of tags (attributes) that are assigned to a given user |
users.deleted_at | Date - When/if the user was deleted |
users.start_date | Date - When the user began employment |
users.avatar | String - URL of the user's avatar image |
Example
curl -X GET https://api.getdx.com/users.listAttributable -H 'Authorization: Bearer <API_TOKEN_HERE>'
{
"ok": true,
"users": [
{
"id": "NTEycDM4",
"name": "Martin Lopez",
"email": "[email protected]",
"github_username": "developer123",
"gitlab_username": null,
"additional_github_username": null,
"developer": false,
"tags": [],
"deleted_at": null,
"start_date": "2008-03-24",
"avatar": null
}
]
}
users.attributes.update
This endpoint allows you to create and update custom attributes for a given user. Doing so will replace any existing attributes in the specified attribute groups. If you send an attribute group name, we will do a case-insensitive search on the existing groups already in your account and either use that if it exists, or create a new one.
Parameters
Name | Type | Required | Description |
string | Yes | Email of the user to update attributes for | |
attributes | array | Yes | Array of attribute objects to add/update |
Attribute Object Parameters
Name | Type | Required | Description |
name | string | Yes | Name of the attribute group |
value | string | Yes | Name of the attribute value |
Example request
curl --location --request POST 'https://api.getdx.com/users.attributes.update' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "[email protected]",
"attributes": [
{
"name": "Department",
"value": "Engineering"
},
{
"name": "Location",
"value": "Remote"
}
]
}'
Response
Name | Description |
user.id | ID - ID from DX system |
user.email | String - The email of the user |
user.failures | Array - List of failures if any of the attribute groups failed to update. |
user.attributes | Array - List of all the attributes assigned to the user |
user.attributes.name | String - The name of the attribute group that was updated |
user.attributes.value | String - The name of the attribute value that was updated |
user.attributes.updated | Boolean - Returns true if the attribute was updated during the request |
Upon a successful request, the response will contain all of the attributes that are assigned to the user, with an updated value of true on the ones that were updated as a result of the request.
Example response
{
"ok": true,
"user": {
"id": "user_123",
"email": "[email protected]",
"failures": [],
"attributes": [
{
"name": "Department",
"value": "Engineering",
"updated": true
},
{
"name": "Location",
"value": "Remote",
"updated": true
}
]
}
}