Teams API methods allow you to programmatically retrieve information about certain teams within DX. This data can also be used in conjunction with the Snapshots API to enrich your results.
API Methods
teams.list
Display a list of all the teams that have been conducted along with some basic data about each one.
Response
Name | Description |
teams.ancestors | Array - List of team ids, refers to all the teams that are above the current team in the hierarchy |
teams.id | ID - The ID of the team itself |
teams.parent_id | ID - The ID of the team's parent team |
teams.manager_id | ID - The user ID of the assigned manager |
teams.name | String - The name of the team |
teams.parent | Boolean - Indicates whether or not the team is a parent team |
teams.last_changed_at | Date - The date and time of the last update to the team |
teams.contributors | Number - The count of contributors on the team |
teams.deleted_at | Date - Indicates if and when the team was deleted |
teams.reference_id | String - An ID that's internal to your organization. We can store this ID during your team importing process (see 'Team tree with ID's). |
Example
curl -X GET 'https://api.getdx.com/teams.list' -H 'Authorization: Bearer <your-token>'
{
"ok": true,
"teams": [
{
"ancestors": [
"LTE",
"MTUxODcx",
"NTA2MTg",
"NTA2MTk",
"NTA4Nzc"
],
"id": "NTA4Nzc",
"parent_id": "NTA2MTk",
"manager_id": "NTEyMDUw",
"name": "Core Data",
"parent": true,
"last_changed_at": "2024-03-19T22:36:47.448Z",
"contributors": 0,
"reference_id": "06BEC4E0-5A61-354E-08A6-C39D756058AB"
},
]
}
teams.get
This endpoint returns the user objects for the lead and contributors of a given team.
Required Arguments
if looking up by team_id
Name | Description |
team_id | String - The ID of the team. Can be retrieved from the teams.list function. |
if looking up by reference_id
Name | Description |
reference_id | String - An ID that's internal to your organization. We can store this ID during your team importing process (see 'Team tree with ID's). |
Response
Name | Description |
team.lead | Object - The user object of the person who is assigned as the leader of the team |
team.contributors | Array - The list of user objects of the people assigned as contributors to the team |
Example
curl -X GET 'https://api.getdx.com/teams.get?team_id=<TEAM_ID>' -H 'Authorization: Bearer <your-token>'
{
ok: true,
team: {
lead: {
id: "1234",
name: "Jane Doe",
email: "[email protected]",
avatar: "",
github_username: "",
developer: true,
tz: "",
...
},
contributors: [{...user}, {...user}, {...user}]
}
}
teams.auditTrail
Display the audit trail that can also be found in the app here.
Required Arguments
Name | Description |
cursor | String - The value necessary for fetching the next page of data. Extracted from any payload on the |
Response
Name | Description |
events | Array - List of all the event objects |
events.id | ID - Id of the change event |
events.actor | String - Email of the user responsible for the change |
events.team | String - Name of team |
events.action | Enum - One of: |
events.metadata | JSON - describes the before and after states of change |
events.created | Unix Timestamp - Date that the change event occurred |
Example
curl --X GET 'https://api.getdx.com/teams.auditTrail?cursor=<CURSOR_VALUE>' -H 'Authorization: Bearer <your-token>'
{
"events": [
{
"id": "MTQxMDb1",
"actor": "[email protected]",
"team": "AI",
"action": "change_name",
"metadata": {
"to": "Artificial Intelligence",
"from": "AI"
},
"created": 1737557847
},
{
"id": "MTM1OTEf",
"actor": "[email protected]",
"team": "Core Data",
"action": "change_manager",
"metadata": {
"to": {
"id": "MTA1MjA2OA",
"name": "Jane Doe",
"email": "[email protected]"
},
"from": {
"id": "NTYzNTgz",
"name": "Martin Lopez",
"email": "[email protected]"
}
},
"created": 1736515821
},
]
}
teams.findByMembers
Find team by list of member emails
Required Arguments
Name | Description |
team_emails | String - a comma separated list of all team members for a team, This list can optionally include the team manager/lead. Required |
Response
Name | Description |
Id | Object - details of matched team |
name | ID - Id of team |
members | Array - list of team members/contributors |
members.id | ID - id for a single member/contributor |
members.name | String - member/contributor name |
members.email | String - member/contributor email address |
manager | Object - Details of the team manager/lead |
manager.id | ID - id for the team manager/lead |
manager.name | String - name of the team manager/lead |
manager.email | String - email address of the team manager/lead |
Example
curl --X GET 'https://api.getdx.com/[email protected],[email protected]' -H 'Authorization: Bearer <your-token>'
{
"team": {
"id": "MTYyMDQz",
"name": "Core Data",
"members": [
{
"id": "NjA",
"name": "Chester Tester",
"email": "[email protected]"
},
{
"id": "Mzc0OTQw",
"name": "Jane Doe",
"email": "[email protected]"
}
],
"manager": {
"id": "NTEyMDUw",
"name": "John Doe",
"email": "[email protected]"
}
}
}
Error codes
Error Code | Description |
| Could not parse the team_emails parameter in a way that was useable, check that the sent value is a list of valid emails that are comma separated. |
| The server could not identify any active users for the authorized account with the emails sent. |
| No teams could be found with the emails provided. |