# CSV file CSV directory import

<!-- Generated by scripts/generate.ts. Do not edit. -->

Export your people as a CSV file with the columns below and upload it in this setup; each new upload applies only the differences.

:::caution[Verification]
Not yet verified on a real CSV file tenant. It was written from the public CSV file documentation, so labels in the admin console may differ slightly.
:::

The values in braces, such as `{acs_url}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="export"></a>

### Export your people

Export everyone who should be in the directory from your HR system or spreadsheet as one CSV file with a header row. Each upload replaces the whole directory, so always export everyone, not just recent changes.

</li>

<li class="idp-step">

<a id="external-id"></a>

### Add the external_id column

Add an external_id column with a value that never changes for each person, such as an employee ID. It is required and must be unique in the file. A person whose external_id changes is removed and added again as someone new.

</li>

<li class="idp-step">

<a id="user-name"></a>

### Add the user name or email

Add a user_name column, an email column or both. Each row needs one of the two; when user_name is empty, the email is used. User names must be unique, and emails must be valid addresses.

</li>

<li class="idp-step">

<a id="optional-columns"></a>

### Add the optional columns

You can also add given_name, family_name, display_name, active, title, department and employee_number. Set active to true or false; it is true when empty. Column names are not case-sensitive, and a file with any other column is refused.

</li>

<li class="idp-step">

<a id="groups"></a>

### List each person's groups

To sync groups, add a groups column with the person's group names separated by semicolons, such as "Engineering;Managers". Groups are created from the names in the file and removed when no row names them.

</li>

<li class="idp-step">

<a id="limits"></a>

### Check the file limits

A file can be at most 10 MiB and hold at most 50,000 users. A file with errors is refused as a whole, with up to 20 problem rows named, and nothing changes.

</li>

<li class="idp-step">

<a id="upload"></a>

### Upload the file

Upload the file in this setup. Only the differences from the current directory are applied: new people are added, changed people are updated and people missing from the file are removed.

</li>

<li class="idp-step">

<a id="upload-again"></a>

### Upload again to keep it current

Upload a new full export whenever people join, change roles or leave. As a safety check, a file that would remove more than half of a directory of 20 or more users is refused; check the export if that happens.

</li>

</ol>

## Sources

- [RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files](https://www.rfc-editor.org/rfc/rfc4180), read on 2026-10-29
