Team hierarchies

DX lets you define teams and organizational hierarchies to power report filtering and roll‑ups across the platform.

Caution: Editing team hierarchies can significantly impact your DX setup. Incorrect changes may break reporting, access, or team assignments. Review all changes carefully before publishing, or contact your DX account manager for assistance.

Before you begin

  1. Export a copy of your current team structure and save it for reference.
  2. A team can only have one manager. If a team has multiple managers, choose one type of manager (EM, DM, PM) to default to as lead, and be consistent.
  3. Review CSV formats and required columns in our CSV formats reference (Google Sheet).

Upload team CSV

  1. Team hierarchy
  2. Team hierarchy with unique IDs
  3. Workday RaaS (beta)
  4. Management hierarchy

Most organizations should use this format. It maps individual contributors to a team name and a manager email.

Step 1: Prepare your CSV

  1. Ensure the CSV is comprehensive, with every desired individual contributor assigned to a team.
  2. Start from your current structure export if helpful.

Step 2: Upload the file

  1. Go to Admin → Org CSVs.
  2. Select the Team hierarchy upload type.
  3. Select or drop your CSV file.

Step 3: Map CSV columns

  1. For each hierarchy level, map Team name and Manager email. DX will attempt to auto‑map; confirm and adjust as needed.
    • Uploads can be processed without a manager email; if missing, the manager defaults to the user performing the upload.
  2. Map all columns that contain team names. Use + Add Another Level to add the correct number of layers in your team structure.
  3. Click Preview structure.

Step 4: Review team structure logic

  1. Select merge logic:
    • Choose the logic that consolidates best. Typically, teams will be consolidated based on team lead and team name.
    • Try different merge logics to maximize assigned contributors while minimizing duplicate teams.
  2. Select minimum team size:
    • Recommended: No Minimum.
    • Note: Teams with three or fewer contributors are not displayed individually in the UI by default. Their data rolls up to larger groups.
    • If you select No Minimum, the number of contributors assigned to teams should match your CSV. If not, try a different deduplication logic.
    • If you set a minimum team size, discrepancies may be due to teams being dissolved/ignored by the importer.
  3. Create shareable preview: Click Create sharable preview to generate a link for stakeholders or your DX support team.
  4. Click Review changes to proceed.

Step 5: Review and publish

  1. Review changes as interpreted by the importer:
    • Teams being updated
    • Teams being created
    • Teams being deleted
    • Contributors not found: This can be due to missing Slack/Teams membership where the DX bot is installed, typos, or email domain mismatches.
  2. Publish changes.
  3. Verify the published structure on the Teams page. You can make manual changes there: add/remove managers, contributors, and teams; and reorder the structure.

Maps individual contributors to a team and assigns teams to reference IDs (if available). Members of a single team go into one cell, with emails separated by commas. Use this format when you have authoritative team IDs and need deterministic merges across uploads.

Step 1: Prepare your CSV

  1. Ensure the CSV is comprehensive, with every desired individual contributor assigned to a team.
  2. Start from your current structure export if helpful.

Step 2: Upload the file

  1. Go to Admin → Org CSVs.
  2. Select the Team hierarchy with unique IDs upload type.
  3. Select or drop your CSV file.

Step 3: Map CSV columns

  1. Each level of the team requires a team name and a manager email. DX will attempt to infer the correct mapping for your CSV columns.
    • Uploads can be processed without a manager email; the manager for teams without one present will default to the user performing the CSV upload.
  2. Map all columns that contain team names. Use + Add Another Level to add the correct number of layers in your team structure.
  3. Click Preview structure.

Step 4: Review team structure logic

  1. Select merge logic:
    • Choose the logic that consolidates best. Typically, teams will be consolidated based on team lead and team name.
    • Try different merge logics to maximize assigned contributors while minimizing duplicate teams.
  2. Select minimum team size:
    • Recommended: No Minimum.
    • Note: Teams with three or fewer contributors are not displayed individually in the UI by default. Their data rolls up to larger groups.
    • If you select No Minimum, the number of contributors assigned to teams should match your CSV. If not, try a different deduplication logic.
    • If you set a minimum team size, discrepancies may be due to teams being dissolved/ignored by the importer.
  3. Create shareable preview: Click Create sharable preview to generate a link for stakeholders or your DX support team.
  4. Click Review changes to proceed.

Step 5: Review and publish

  1. Review changes as interpreted by the importer:
    • Teams being updated
    • Teams being created
    • Teams being deleted
    • Contributors not found: This can be due to missing Slack/Teams membership where the DX bot is installed, typos, or email domain mismatches.
  2. Publish changes.
  3. Verify the published structure on the Teams page. You can make manual changes there: add/remove managers, contributors, and teams; and reorder the structure.

Use this when Workday is your source of truth for the org structure. A static RaaS table can be linked to DX and uploaded through the same UI. Uploading a Workday RaaS CSV still requires a manual upload unless fully automated via a separate setup.

See the Workday RaaS setup guide for more.

Maps individuals and managers based purely on reporting relationships. Use this when explicit team names are not reliable or available. DX will infer team structure from reporting lines during processing.

Step 1: Prepare your CSV

  1. Ensure the CSV is comprehensive, with every desired individual contributor assigned to a team.
  2. Start from your current structure export if helpful.

Step 2: Upload the file

  1. Go to Admin → Org CSVs.
  2. Select the Management hierarchy upload type.
  3. Select or drop your CSV file.

Step 3: Map CSV columns

  1. Each level of the team requires a team name and a manager email. DX will attempt to infer the correct mapping for your CSV columns.
    • Uploads can be processed without a manager email; the manager for teams without one present will default to the user performing the CSV upload.
  2. Map all columns that contain team names.
  3. Click Preview structure.

Step 4: Review team structure logic

  1. Select minimum team size:
    • Recommended: No Minimum.
    • Note: Teams with three or fewer contributors are not displayed individually in the UI by default. Their data rolls up to larger groups.
    • If you select No Minimum, the number of contributors assigned to teams should match your CSV. If not, try a different deduplication logic.
    • If you set a minimum team size, discrepancies may be due to teams being dissolved/ignored by the importer.
  2. Create shareable preview: Click Create sharable preview to generate a link for stakeholders or your DX support team.
  3. Click Review changes to proceed.

Step 5: Review and publish

  1. Review changes as interpreted by the importer:
    • Teams being updated
    • Teams being created
    • Teams being deleted
    • Contributors not found: This can be due to missing Slack/Teams membership where the DX bot is installed, typos, or email domain mismatches.
  2. Publish changes.
  3. Verify the published structure on the Teams page. You can make manual changes there: add/remove managers, contributors, and teams; and reorder the structure.

Automate via API (optional)

If you need to integrate with an external workflow or CI, you can automate team hierarchy updates via the Web API. Three endpoints work together to let you retrieve, preview, and publish hierarchy changes programmatically.

All three endpoints require a Web API key with the snapshots:admin scope.

Step 1: Retrieve your current hierarchy

Use orgfiles.teamHierarchy.get to export your current team structure. The response is in the same format that the .preview and .process endpoints accept, so you can use it as a starting point for modifications.

curl -X GET 'https://api.getdx.com/orgfiles.teamHierarchy.get' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx"

Step 2: Preview changes before applying

Once you’ve modified the hierarchy payload, submit it to orgfiles.teamHierarchy.preview to generate a preview URL. Open the URL to visually QA the proposed structure in the DX UI before committing to the change.

curl -X POST 'https://api.getdx.com/orgfiles.teamHierarchy.preview' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
   --data-raw '{ "teams": [ ... ] }'

The response includes a preview_url you can share with stakeholders for review. You can also finalize the import directly from the preview page in the DX UI.

Step 3: Process the update

After validating with .preview, send the same payload to orgfiles.teamHierarchy.process to apply the changes. Once your automation is tested and stable, you can call .process directly on a schedule—skipping .preview—to keep DX in sync automatically.

curl -X POST 'https://api.getdx.com/orgfiles.teamHierarchy.process' \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
   --data-raw '{ "teams": [ ... ] }'

Processing is asynchronous. A successful response means the job was enqueued; imports typically complete within seconds but may take a few minutes for larger organizations. Pass an optional email parameter to receive a notification when the import finishes.

Team object format

Each object in the teams array uses the following fields:

Field Type Description
name string Team name.
reference_id string A stable identifier for the team. Keeping this consistent across requests preserves historical trend data.
team_lead_email string Email of the team’s manager. Must match an existing user in DX.
parent_team_reference_id string or null reference_id of the parent team, or null for top-level teams.
parent_team_name string or null Name of the parent team, or null for top-level teams.
contributors array of strings Email addresses of individual contributors on the team.

Limitations

These endpoints are 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.

Troubleshooting

Try a different merge logic and ensure manager emails are normalized.

Confirm Slack/Teams membership where the DX bot is installed, check for typos, and verify email domains.

Teams with three or fewer members do not display individually by default; their data is rolled up.

Use No Minimum and test alternate deduplication logic.

Choose one default manager type and apply consistently across the CSV.