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
teams.get
teams.auditTrail
teams.findByMembers

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_metadata.next_cursor` field.

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: `change_manager`, `change_name`, `change_parent`, `create`, `change_name`, `add_contributor` or `delete`
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	Array - a 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/teams.findByMembers?' -H 'Authorization: Bearer <your-token>'
--form 'team_emails="<EMAIL ARRAY>"'

{
    "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]"
        }
    }
}