orgfiles.teamHierarchy.update

Create or update selected teams in your team hierarchy without replacing the entire account hierarchy.

To replace the full org chart (and soft-archive every team omitted from the payload), use orgfiles.teamHierarchy.process instead.

orgfiles.teamHierarchy.preview uses full-replacement semantics, not incremental apply. To preview an incremental change, merge your edits into a full hierarchy payload before calling preview.

Facts


Method	`POST https://api.getdx.com/orgfiles.teamHierarchy.update`
Required scopes	`snapshots:admin` and `snapshots:read`

Arguments

Required arguments

Name	Type	Description
`teams`	`Array<HierarchyTeam>`	Array of hierarchy team objects to create or update.

Optional arguments

Name	Type	Description
`email`	`Text`	Email address to notify upon success or failure of import.
`force`	`Boolean`	Set to `true` to import while a snapshot is live or in its retroactive application window.

This API method allows you to create and update selected teams in DX. For each team you include, apply semantics match orgfiles.teamHierarchy.process. The only intentional difference is how omitted teams are treated.

	`process`	`update`
Teams in the payload	Created or updated	Created or updated
Teams omitted from the payload	Soft-archived	Left unchanged
Parent / contributors on a listed team	Same rules as `process`	Same rules as `process`

Do not send a partial list of teams to process unless you intend to archive every team you left out. Prefer update for incremental changes.

Based on the data you provide for teams in the request, DX automatically performs the following operations:

Creation: New teams included in your request are created in DX.
Updates: DX stores customer-provided reference IDs to enable updating existing teams.
No archival by omission: Teams in DX that are not included in your request are left as they are. To archive teams, use process with the full desired hierarchy.

For each listed team object, field apply matches process:

Parent: Both parent_team_reference_id and parent_team_name must be present, or both blank/null. Blank or omitted parent fields make that team a root. To keep an existing child under its current parent, send the current parent fields (for example from orgfiles.teamHierarchy.get with format=import). The parent may already exist in the account even if that parent team is not a row in this payload.
Membership: contributors is the complete member list for that team after the job runs. Use [], or omit contributors, to clear members on that listed team. Unknown contributor emails are skipped. The same email on multiple teams in one payload follows the same first-wins behavior as process.
Team lead: team_lead_email must belong to an existing user. The same person may lead multiple teams. Being lead does not add them as a member unless their email is in contributors.
Moving people: A person can only be on one team. Listing them on a team in this request moves them off their previous team, even if that previous team is not in the payload.
Identity: Matched by stable reference_id. A new or mistyped reference_id creates a new team.

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. There is no public status-polling method for the import_id today.

Reference IDs

Every team must include a nonblank reference ID. 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.

Prefer copying IDs from orgfiles.teamHierarchy.get with format=import rather than retyping them.

Example request

Update one team’s membership and keep its place in the hierarchy, without touching other teams:

curl -X POST 'https://api.getdx.com/orgfiles.teamHierarchy.update' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
   --data-raw '{
    "email": "email.to.notify@example.com",
    "teams": [
      {
        "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", "contributor2@example.com"]
      }
    ]
}'

In this example, only ds-003 is created or updated. Every other team in the account is left unchanged (not archived).

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 bearer token for authentication.
`invalid_auth`	The provided bearer token is invalid. This can happen if the token 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 20 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 application window. Send `force=true` to import anyway.
`invalid_email`	The format of the email address to notify of completion or failure is invalid.