---
title: "Bulk import teams"
canonical: "https://support.appfire.com/space/FD/1802109245/Bulk%20import%20teams"
format: markdown
---
> Macro (aura-html)

When creating new team structures or making significant modifications to existing ones, consider bulk-importing your teams via a CSV file upload. To edit teams directly in Flow, learn more about [Team management](https://appfire.atlassian.net/wiki/spaces/FDDRAFT/pages/2893120193) and [Team details](https://appfire.atlassian.net/wiki/spaces/FDDRAFT/pages/2894463303).

> ℹ️ Use either the Flow REST API or the Teams page to bulk upload or update team structures.

## Prepare a CSV file to bulk import teams

Before bulk importing users, create a CSV file with the following columns:

- Name
- Email
- Team name
- Parent team name (if applicable)
- Membership visibility: Yes, No, or Inherit
- Membership type: Viewer or Contributor
- Attributes, for example, Country, Seniority Level, Engineer Type (if applicable)

If you already have teams and users in Flow, simplify this process by downloading your existing team and user structure from the Teams page, then using this as a template for your changes. This ensures your CSV file has the correct columns and setup, and gives you a reference for how your users are already structured.

> 📝 - When adding a new user or team, if membership visibility is left blank, we will default to Inherit. For an existing user or team, if membership visibility is left blank, we will not update this field from its previous value. Make sure all team names are unique.
> 📝 - If you want to assign specific user attribute values to your imported team members, you need to [configure user attributes](https://appfire.atlassian.net/wiki/spaces/FD/pages/3044311307) for your organization first.

Example CSV file:

```
Name,Email,TeamName,ParentTeamName,Membership Visibility,Membership Type,Country
Stephanie,user1@email.com,team1,,Yes,Contributor,USA
Arya,user2@email.com,team1,,No,Viewer,India
Ben,user3@email.com,team2,team1,Australia
Devon,user4@email.com,team1,,No,Scotland
Alex,user5@email.com,team1,Inherit,Viewer,Canada
```

## Bulk importing teams via the API

To bulk import teams using the Team membership API:

1. Create an API key. To learn more about creating an API key, see [Flow REST API introduction](https://appfire.atlassian.net/wiki/spaces/FDDRAFT/pages/2894299389).
2. Make a `POST` request using the following URL:
  - `https://<workspace>.appfireflow.com/v3/customer/core/team_membership/bulk_import/`
3. Choose the CSV file you created.
4. Specify the `import_type` as either `overwrite` or `update`.
5. Set any additional parameters for your upload. Find these additional parameters below.
6. Click **Send**.

Additional parameters for **overwrite**:

- `add_new_apex_users`
- `remove_memberships`
- `remove_empty_teams`
- `remove_teams`

Additional parameters for `update`:

- `add_new_apex_users`

Additional parameter details:

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| `csv_file` | file | Required, CSV file of teams, team memberships |
| `import_type` | string | Required, **overwrite **or **update** |
| `add_new_apex_users` | boolean | True/false |
| `remove_memberships` | boolean | True/false (only with overwrite) |
| `remove_empty_teams` | boolean | True/false (only with overwrite) |
| `remove_teams` | boolean | True/false (only with overwrite) |

To verify that your CSV import was successful, find your upload in the [team import history](https://help.pluralsight.com/hc/en-us/articles/24352923743508#history) page.

## Bulk importing teams using the Teams page

To bulk-import teams using the Teams page:

1. Go to **Settings** > **User Management** > **Teams**.
2. Click **Import Teams** .
3. Click the **CSV** button in the top right. To [import your teams from GitHub or ADO services,](https://help.pluralsight.com/hc/en-us/articles/24352959963540) use the **Integration import** option. A **Bulk import teams** modal displays.

![Bulk import teams modal in Flow.](media://46793722-f73e-485e-adfc-160fb3df636f)

4. On the modal, you have several options:

- Click **Download current team structure** if you want to download the most up-to-date file with teams. You can then review and update it if needed. If you are a new user and have no teams in Flow yet, this option will download a file with empty columns but with the required headings. You can then populate it with teams data.
- Click **Update user attribute configuration **if you want to change or review your [user attributes  configuration](https://appfire.atlassian.net/wiki/spaces/FD/pages/3044311307). This option opens the *User attribute* page in a new window.

> 📝 - Be sure the attributes in your file match exactly those you defined in Settings.
> 📝 - Remember to add a comma between multiple values when using multi-select for a custom attribute.
> 📝 
> 📝 ![A correct example of the multi-select custom values in the CSV file.](media://0184a12b-3bfd-4695-8b43-07fe30436182)
> 📝 
> 📝 - Double-check if the comma delimiter is placed between the individual values. Attributes with typographical errors, such as “Ja,va,” will not be imported (since the “Ja” and “va” attribute values do not match the programming language names configured in Settings).
> 📝 
> 📝 ![An incorrect example of the multi-select custom values in the CSV file.](media://f7bf7996-2839-4206-824e-679c3d01b340)

- Click **Bulk import with AI transformation** if you have a file from another source (for example, Workday) and would like to adjust it to Flow’s format using AI.

> ℹ️ The **Bulk import with AI transformation** feature is currently in closed beta.

If you choose to use AI to help you format your CSV file:

a). On the **AI Transformations** modal, click **New Transformation**.

b). The **AI Transformation Preview** modal displays. Click **Choose the CSV** to add a file you want to use for future team import. 

c). The **AI Transformation Preview** displays up to the first ten users in your file. The changes (transformations) you introduce in this file preview apply to all users.

![AI Transformation preview of the uploaded CSV file.](media://763980f4-75a3-4ef4-83ba-a029504f43da)

In this preview, the **Flow CSV headers** show optional and required (marked with an asterisk) headers in Flow. The **Imported CSV headers** are the headers from the source app (in this example, from Workday). 

AI matched the Workday headers with the Flow ones. You can open a dropdown for each imported CSV header to see if there is a better header to match.

When data is pre-filled, it indicates the AI has high confidence that your source file columns align with Flow’s expected format. For example, standard identifiers like **Name** and **Email** are typically matched automatically with high accuracy.

If the AI is uncertain about a data mapping, it will flag the entry with a yellow exclamation mark or a red outline, prompting you to review or manually correct the selection.

**Examples**

| **AI suggestion** | **Explanation** |
| --- | --- |
| ![Yellow exlamation mark with a tooltip on the AI Transformation Preview modal.](media://5c663916-18ba-476f-9ceb-eec38f70ee97) | The AI has identified the **Teams** header within your Workday file and requires confirmation to proceed. To validate this mapping, click the **checkmark** button; the AI will then begin processing the underlying data based on your selection. |
| ![AI asks how to map imported header.](media://39f6b5b2-785b-4c4c-b679-23889af892e5) | AI has found a potentially matching header but is unsure how to map it. The tooltip suggests mapping source numeric values to default [user attribute](https://appfire.atlassian.net/wiki/spaces/FD/pages/3045031988) values.<br>Click the pen icon if you want to edit the rule.<br>For example: “Map 4 to Middle, 5 to Senior, 6 to Principal” or “4 → Middle, 3-> Senior, 6-> Principal.”<br>Otherwise, click the yellow exclamation mark and confirm. Next, AI will process the data under the imported header based on that rule.<br>> ℹ️ The user attributes you can see on the preview are the user attributes currently set for your organization.
> ℹ️ 
> ℹ️ If no attributes were configured for your organization yet, the CSV preview displays only default attributes. 
> ℹ️ 
> ℹ️ Click the **Update user attribute configuration** button in the top-right corner. This will take you to the *[User attributes](https://appfire.atlassian.net/wiki/spaces/FD/pages/3044311307)*[ configuration](https://appfire.atlassian.net/wiki/spaces/FD/pages/3044311307) page where you can manage the existing attributes and add new ones. |
| ![ai-transformation-missing data.png](media://66294204-230f-4203-b8ca-de36a8e9ef4f) | AI has not found any matching imported header for the required column.<br>If none of the other headers match and the column is required, you will need to update the file to include the missing data. And then, re-upload it for a new transformation. |
| ![AI suggestion next to the Can view other metrics header.](media://96e8297a-8c3a-4db3-94dc-fd3ffee5d5ea) | AI has found a potentially matching header but is unsure how to map it. Use the “yes,” “no,” or “inherit” options to map “Yes” and “No” from the source file. For example: “Yes → inherit, No → inherit.”<br>This is a non-required column. If you leave it as it is, all users will be mapped to “inherit” by default. |
| ![AI suggestion next to the Membership type column.](media://d690ad78-0f25-4032-af37-ac044c457ba9) | In this example, AI has found a potentially matching header but is unsure how to map it.<br>Use source-specific values to map users to contributors or viewers, or a more general prompt to process the transformation.<br>For example: “Map all to contributor.”<br>This is a non-required column. If you leave it as it is, all users will be mapped to “contributor” by default. |
| ![Unmapped header on the Can view others metrics column in the ai transformation preview.](media://69963f18-2f7f-442a-97a5-2280d7d3857c) | AI has not found any matching imported header for the non-required column.<br>You can select one manually or leave it as it is. Unmapped headers are excluded from the import. |

> 📝 When creating a value mapping rule for any column, you can use microprompts written in natural language. If the tooltip suggests specific values to use, be sure to type them exactly as they appear (they are case-sensitive).

After you enter your prompt, AI may require further input from you. In such a case, the header will again be marked with a yellow exclamation mark. Type in another prompt to resolve it. Or, if it’s a non-required column, you can leave it as it is. 

Note that you cannot proceed with the transformation unless you have resolved all issues in the required fields. You can leave unresolved issues in the non-required columns. In such a case, the column will be excluded from the import. 

d). Click **Next**.

e). You are back on the **AI transformations** modal, where you can see a list of your transformed CSV files. 

![AI Transformations modal. There are two files. One has the Finished status, the other one has Draft.](media://063e68ae-f9dc-42d1-b5fb-5b98a6c7be3a)

Download the file you have just transformed. Note that only the files with a **Finished** status are ready for download. Click **New Transformation** to process another CSV file with an AI, or **Back** to return to the **Bulk import teams** modal.

5. In the **Bulk import teams** modal, select your file using the **Choose CSV** button. A **CSV** **import selections** modal displays.

![CSV selections modal.](media://e6e4ff33-fad7-4441-8bc6-e8ea9a86b93d)

6. On this modal, you can:
  1. Select **Update existing teams** to add any new teams and team members from your file, but will not remove or edit any teams that are not explicitly included in the file. With **Additional actions**, you can:
  2. Check **Add user if not found** to add users included in your file but not found in Flow.
  3. Check **Update user attributes** to update user attributes (leave blank if you upload teams with user attributes for the first time).
7. Select **Completely overwrite teams** to replace the current team setup with the one you created within the CSV file. For the overwrite option, you can fine-tune what you want to keep and what you want to officially overwrite with **Additional actions**:
  1. **Add user if not found**
  2. **Update user attributes**
  3. **Remove teams not in CSV file**
  4. **Remove memberships not in CSV file**
  5. **Remove teams with no members**
8. On the **Confirm bulk import** screen, review your import settings and confirm with **Import CSV**. Otherwise, click **Back** to make changes.

![Confirm bulk import modal.](media://c20375d2-66d8-4409-b5e9-78019d52f58a)

9. This starts the import and takes you to the *Team import* history page.
10. Check the status of your recent import in the **Status** column:
  1. If the import is still processing, the status will be <span style="color: #0747a6">**Queued**</span>.
  2. If there are no errors in the CSV and the import is successful, the Status column shows <span style="color: #006644">**Success**</span>.
  3. If there are errors in the import, a <span style="color: #ffc400">**Partial Success**</span> or <span style="color: #bf2600">**Failed**</span> status appears in the Status column.

Mouse over the finished status (Partial Success, Success, or Failed) to review your import.

![Team import history.](media://dd629a4c-4d69-410f-a82a-3d1ad8e4454a)

11. Check the status of the attributes import in the **Attributes Update** column.
12. If there are no errors in the CSV and the import is successful, a <span style="color: #006644">**Success**</span> :check_mark: status icon appears in the **Attributes Update** column.
13. If there are errors in the import, a <span style="color: #ffc400">**Partial Success **</span>🟡  or <span style="color: #bf2600">**Failed **</span>:cross_mark: status icon appears in the **Attributes Update** column. Click the **Details link** next to the status icon to review the errors.

![A modal explaining the unsuccessful user attribute import.](media://0d90b69c-2870-4c59-bc02-5e4f96610937)

If the team import was **Failed** or **Partial Success**, Flow creates an updated CSV file including any errors during the import process. Click the **download** button next to your specific import to download a copy of the updated CSV file.

## Bulk importing multi-tiered nested teams

When importing teams with multiple nested team levels, use the ParentTeamName column to associate each nested team with to most immediate parent team.

> ✅ If one or more parent teams have nested users but no native users, you may need to add a fake user to the empty team to recreate the hierarchy.

Alternatively, manually create any empty teams after you import your file, then nest the nested teams. 

Example Team Structure:

- King of the Castle: 0 users, 10 nested users
- Front End: 0 users, 10 nested users
- FE A: 2 users, 0 nested users
- FE B: 1 users, 2 nested users
- FE B1: 2 users, 0 nested users

In the above team structure, the top two team levels, King of the Castle and Front End, do not have any native users.

In this case, Flow creates the Front End team because of its immediate association to its nested teams, FE A and FE B. The main parent team, King of the Castle, must be added manually.

Alternatively, a user must be added to either the King of the Castle or to the Front End team.

The image below shows what the file looks like without adding an additional user, fake or otherwise:

![Example CSV without King of the Castle team.](media://f570e483-921e-4592-8fa2-8df83971c156)

To create the top-level team, add the team to the file:

![Example CSV including King of the Castle team.](media://6ddfb6bb-0af9-4087-a01e-98928813d329)

- Line 7 adds a user directly to the top parent team.
- Line 8 adds a user directly to the Front End team, thereby associating Front End to the parent team.

Once you have your team structure mapped out in your file, follow the steps in the previous sections to upload and import it.