Skip to main content
Import users in bulk from a CSV file when you need to add or update more than a handful at once. Each imported user carries the csv source tag, and re-uploading an updated file keeps them in sync. CSV import works well for initial loads and one-off updates. If your HR system is the ongoing source of truth, use HR sync instead. You can also include custom attributes you have defined as columns in the file. In Directory → Users, click the arrow next to + User, then choose Import via CSV.
Re-upload whenever your list changes. You can combine CSV import with HR sync: many teams seed the directory with a CSV, then connect their HR system to keep it current. See when to use HR sync.

​
File requirements

Imports are all-or-nothing. If the file has a structural problem, or any row fails validation, nothing is imported. Iru returns a report of every problem so you can fix the file and upload again.

​
Columns

The import dialog lists every column your file can include: required core columns, optional core columns, and any custom attribute columns from your schema. Use the sample from Download sample.csv as your header template. When your column names match the sample, each row’s values populate the matching profile fields on the user identified by externalId.

​
Required

Every row must include a non-empty value for each of these columns.

​
Optional

Leave a cell blank, or omit the column entirely, when a value is not needed. If domain is blank, Iru derives it from the email address.

​
Custom attributes

After you define custom attributes in your schema, the import dialog lists them under Custom attribute columns, named categorySlug.attributeSlug from the category slug and attribute slug. For example, department and title in a category whose slug is extrainfo appear as extrainfo.department and extrainfo.title. Add one column per attribute to your CSV header. Core column names must match exactly; custom attribute column names ignore capitalization and spacing.

​
Sample file

In the import dialog, click Download sample.csv for a starter file with all core columns and one example user. If your schema includes custom attributes, click the arrow next to Download sample.csv, then choose With custom attributes. That sample adds a column for each custom attribute in your schema and leaves those cells blank in the example row so you can fill them in. The core columns and example user stay the same. Replace the example user with your own rows and keep the header names unchanged.

​
Field behavior

​
Domain derivation

  • If domain is blank, Iru takes it from the email address (jane.doe@example.com becomes example.com).
  • If domain is provided, that value is used as-is.
  • A domain that does not already exist is created automatically.

​
Phone numbers

Phone values are normalized to E.164 (a leading +, country code, then digits, with no spaces or punctuation), the same way phone numbers are stored everywhere else in Iru Identity.
Numbers outside North America must include a + and their country code (for example +44…). Without a leading +, a number is assumed to be a 10-digit North American number and gets +1.

​
Addresses

Iru stores an address whenever any address column has a value. A partial address (only locality and country, for example) is fine; missing parts stay blank. If every address column is blank, no address is stored.

​
Run the import

The Import users via CSV dialog shows the required and optional core columns, any custom attribute columns from your schema, and Download sample.csv with an arrow for With custom attributes. Drag a file onto the upload area or browse to select one.
1

Start the import

In Directory → Users, click the arrow next to + User, then choose Import via CSV. Review the column list in the dialog against the tables above.
2

Prepare your file

Click Download sample.csv for a file with core columns and one example user. If your file includes custom attribute columns, click the arrow next to Download sample.csv, then choose With custom attributes. Replace the example user with your own rows and keep the sample header names so each row maps to the right user and profile fields.
3

Choose your file

Select your CSV or drag it onto the upload area.
4

Upload and validate

Iru validates the whole file first. If validation passes, rows are accepted and users are created or updated in the background. If validation fails, the dialog shows a report and nothing is imported.
5

Review the result

A successful upload reports how many users were staged and adds the import to your history, where you can review the outcome for each row.
After you upload, Iru validates the entire file. If validation fails, nothing is imported. Fix the reported problems and upload again. When validation passes, rows are accepted and staged, and users are created or updated in the background. Check the import in your history to confirm each row. A row can still fail at apply time after the file is accepted; correct those rows and re-import them. See Validation and errors for the two stages of checks.

​
Create vs. update: re-uploading

Users are matched on externalId within the csv source:
  • A new externalId creates a new user with the end-user role.
  • An existing externalId updates that user’s profile from the row. Role and group memberships do not change.
Re-upload a corrected or expanded CSV at any time to keep imported users in sync. Every externalId in a file must be unique.
Re-upload the complete current file each time, not just the rows you changed. Each import is matched on externalId.

​
Validation and errors

Validation runs in two stages. Until the file is fully accepted, nothing is imported.
The file cannot be processed. Common causes include a duplicate column, a missing required column, an empty file, a header with no data rows, or more rows than the limit. Fix the file and upload again.
The file is well-formed, but one or more rows are invalid. Iru returns every problem with the line (the header is line 1, so the first data row is line 2), the column at fault (blank for whole-row issues), and a message. For example:Fix the listed rows and re-upload.
After a file is accepted, rows are applied in the background. A row can still fail at this stage if, for example, the email is already in use by another user or a value conflicts with a unique attribute. These apply errors are recorded on the import batch with the row’s externalId, username, and error details. Correct those rows and re-import them.

​
When to use HR sync instead

Re-upload a CSV whenever your list changes and Iru re-checks every row. For continuous, hands-off provisioning, connect your HR system as the authoritative record instead.
You can use both. Setup for HR sync is covered in Directory Sync.

​
Next steps

Connect your HR system

Automate creates, updates, and removals on a schedule.

Design your schema first

Define required and unique attributes before you import.

Manage individual users

Edit, suspend, and invite the users you’ve imported.

Organize into groups

Turn your imported users into assignable groups.