View all methods

orgfiles.teamHierarchy.process

Update your team hierarchy in DX.

Facts

Method	POST https://api.getdx.com/orgfiles.teamHierarchy.process
Required scope	snapshots:admin

Arguments

Required arguments

Name	Type	Description
teams	Array<HierarchyTeam>	Array of hierarchy team objects.

Optional arguments

Name	Type	Description
email	Text	Email address to notify upon success or failure of import.

Usage info

This API method allows you to create and update your organization’s team hierarchies within DX. Based on the data you provide, DX automatically performs the following operations:

The system will automatically synchronize your team hierarchy based on the provided data:

• Creation: New teams included in your request are created in DX.
• Updates: DX stores customer-provided reference IDs to enable updating existing teams.
• Archival: Teams in DX that are not included in your request are automatically archived.

The process to import the data is done asynchronously. A successful response means the job was successfully enqueued, errors on the endpoint are for invalid formats. The import process is typically done in seconds, but can take up to a few minutes to fully process for larger organizations. An email parameter is optional to be able to notify of the success or failure of the job.

Reference IDs

Maintaining consistent reference IDs for your teams is essential for preserving historical trend data and analytics. When you use the same reference ID across multiple requests, DX persists valuable insights even as team composition, leadership, or organizational positioning evolves over time.

Limitations

This endpoint is unavailable during active snapshot periods or within the retroactive application window (typically three weeks following snapshot completion). Updates during this timeframe must be done manually in the DX platform.

Example request

This is an example request:

curl -X POST 'https://api.getdx.com/orgfiles.teamHierarchy.process' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
   --data-raw '{
    "email": email.to.notify@example.com",
    "teams": [
      {
        "name": "Engineering",
        "reference_id": "eng-001",
        "team_lead_email": "manager@example.com",
        "parent_team_reference_id": null,
        "parent_team_name": null,
        "contributors": []
      },
      {
        "name": "Data science",
        "reference_id": "ds-001",
        "team_lead_email": "manager_ds@example.com",
        "parent_team_reference_id": null,
        "parent_team_name": null,
        "contributors": []
      },
      {
        "name": "Data child 1",
        "reference_id": "ds-002",
        "team_lead_email": "manager_child_1@example.com",
        "parent_team_reference_id": "ds-001",
        "parent_team_name": "Data science",
        "contributors": []
      },
      {
        "name": "Data grandchild 1",
        "reference_id": "ds-003",
        "team_lead_email": "manager_grandchild_1@example.com",
        "parent_team_reference_id": "ds-002",
        "parent_team_name": "Data child 1",
        "contributors": ["contributor1@example.com"]
      },
      {
        "name": "Data grandchild 2",
        "reference_id": "ds-004",
        "team_lead_email": "manager_grandchild_1@example.com",
        "parent_team_reference_id": "ds-002",
        "parent_team_name": "Data child 1",
        "contributors": ["contributor2@example.com"]
      },
       {
        "name": "Data child 2",
        "reference_id": "ds-005",
        "team_lead_email": "manager_child_2@example.com",
        "parent_team_reference_id": "ds-001",
        "parent_team_name": "Data science",
        "contributors": []
      },
      {
        "name": "Data grandchild 3",
        "reference_id": "ds-006",
        "team_lead_email": "manager_grandchild_2@example.com",
        "parent_team_reference_id": "ds-005",
        "parent_team_name": "Data child 1",
        "contributors": ["contributor3@example.com"]
      },
      {
        "name": "Data grandchild 4",
        "reference_id": "ds-007",
        "team_lead_email": "manager_grandchild_2@example.com",
        "parent_team_reference_id": "ds-005",
        "parent_team_name": "Data child 1",
        "contributors": ["contributor4@example.com"]
      }
    ]
}'

The payload shown above would create the following team hierarchy in DX:

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	This error occurs if the API request does not include a valid API key for authentication.
invalid_auth	The provided API key is invalid. This can happen if the key is expired or does not exist.
invalid_rows	This error occurs when a team entry has invalid data, such as missing required fields or a team_lead_email that doesn’t exist in your system.
circular_reference	This occurs when teams reference themselves or each other in a loop. A team cannot be its own parent, and teams cannot create circular references (Team A → Team B → Team A).
payload_too_large	The maximum size your teams value can be is 5 MB.
import_in_progress	An existing import for your account is currently in progress.
snapshot_in_progress	A snapshot for your account is live or in its retroactive appliable window.
invalid_email	The format of the email address to notify of completion or failure is invalid.