orgfiles.teamHierarchy.preview

Update your team hierarchy in DX.

Facts


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

Arguments

Required arguments

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

This API method allows you to send in a payload that you’d potentially use to update your organization’s team hierarchies within DX. The response will provide you with a URL that you can preview what the team structure would look like if you were to send your payload to the process endpoint. From the preview URL you also have the option to finish the import through the DX UI.

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.preview' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
   --data-raw '{
    "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"]
      }
    ]
}'

Example response

{
  "ok": true,
  "import_id": "Mjk0OAEMF",
  "preview_url": "https://app.getdx.com/admin/org-csvs/Mjk0OAEMF/preview"
}

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 previewing. 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.