--- title: "Team hierarchies" canonical_url: "https://docs.getdx.com/team-hierarchies/" md_url: "https://docs.getdx.com/team-hierarchies.md" last_updated: "2026-05-29" --- # 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)](https://docs.google.com/spreadsheets/d/19xaJ2Hr2Gd6WotpTqwcz4iZJ4K2VPB2Sl-k_Mlj6qC8/edit). ## Upload team CSV ### Team 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. 1. Start from your current structure export if helpful. #### Step 2: Upload the file 1. Go to **Admin** -> [**Org CSVs**](https://app.getdx.com/admin/org-csv-uploads). 1. Select the **Team hierarchy** upload type. 1. 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. 1. Map all columns that contain team names. Use **+ Add Another Level** to add the correct number of layers in your team structure. 1. 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. 1. Publish changes. 1. Verify the published structure on the Teams page. You can make manual changes there: add/remove managers, contributors, and teams; and reorder the structure. ### Team hierarchy with unique IDs 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. 1. Start from your current structure export if helpful. #### Step 2: Upload the file 1. Go to **Admin** -> [**Org CSVs**](https://app.getdx.com/admin/org-csv-uploads). 1. Select the **Team hierarchy with unique IDs** upload type. 1. 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. 1. Map all columns that contain team names. Use **+ Add Another Level** to add the correct number of layers in your team structure. 1. 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. 1. Publish changes. 1. Verify the published structure on the Teams page. You can make manual changes there: add/remove managers, contributors, and teams; and reorder the structure. ### Workday RaaS (beta) 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](https://docs.getdx.com/workday-raas/) for more. ### Management hierarchy 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. 1. Start from your current structure export if helpful. #### Step 2: Upload the file 1. Go to **Admin** -> [**Org CSVs**](https://app.getdx.com/admin/org-csv-uploads). 1. Select the **Management hierarchy** upload type. 1. 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. 1. Map all columns that contain team names. 1. 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. 1. Publish changes. 1. 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 an organization token with the `snapshots:admin` scope. ### Recommended workflow #### Step 1: Retrieve your current hierarchy Use [orgfiles.teamHierarchy.get](https://docs.getdx.com/webapi/methods/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. ```bash 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](https://docs.getdx.com/webapi/methods/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. ```bash 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](https://docs.getdx.com/webapi/methods/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. ```bash 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. | > Maintain consistent `reference_id` values across requests. When DX recognizes the same reference ID, it updates the existing team rather than creating a duplicate, preserving historical data even as team composition changes. ### 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 ### Duplicate teams or unexpected splits Try a different merge logic and ensure manager emails are normalized. ### Missing contributors Confirm Slack/Teams membership where the DX bot is installed, check for typos, and verify email domains. ### Team visibility Teams with three or fewer members do not display individually by default; their data is rolled up. ### Count mismatch between CSV and assigned contributors Use No Minimum and test alternate deduplication logic. ### Multiple managers Choose one default manager type and apply consistently across the CSV. --- ## Sitemap [Overview of all docs pages](/llms.txt)