Skip to main content
When you need to add or update more than a handful of people at once, import them in bulk from a CSV file. Imported users are attributed to a dedicated csv source and are kept in sync when you re-upload, which makes CSV import a lightweight alternative to a full HR-system connector when you just need to load a list of people. You start an import from Directory → Users.
CSV import is repeatable - re-upload an updated file whenever your list changes. If your HR system is the system of record for who works at your company, connect it instead so the directory stays current automatically - see when to use HR sync.

​
File requirements

RequirementDetail
FormatComma-separated values (.csv).
EncodingUTF-8. A leading byte-order mark (as Excel adds) is accepted and ignored.
First rowA header row naming the columns.
Header namesCase-sensitive and must match exactly - externalId, not ExternalID.
Unknown columnsSkipped. Columns that aren’t in the list below are ignored; only the documented columns are imported, and custom attributes can’t be set via CSV.
Maximum rows50,000 data rows per upload.
Maximum file size16 MB.
Imports are all-or-nothing. If the file has a structural problem, or any row fails validation, nothing is imported - you get a report of every problem so you can fix the file and upload again.

​
Columns

​
Required

Every row must have a non-empty value for all of these.
ColumnDescriptionRulesExample
externalIdYour stable identifier for the user - the key used to match them on re-upload.Non-empty; unique within the file.EMP-10482
usernameThe user’s login username.Non-empty.jane.doe
emailThe user’s primary email address.A valid, bare address - no display name (Jane <jane@acme.com> is rejected).jane.doe@acme.com
firstNameGiven name.Non-empty.Jane
lastNameFamily name.Non-empty.Doe

​
Optional

Leave the cell blank, or omit the column entirely, when not needed.
ColumnDescriptionRulesExample
domainThe user’s domain.If blank, derived from the part of email after the @. Set it only when it should differ.acme.com
streetAddressStreet line of the address.Free text.1 Market St
localityCity / town.Free text.San Francisco
regionState / province / region.Free text.CA
postalCodePostal / ZIP code.Free text.94105
countryCountry.Free text (e.g. an ISO country code).US
phonePhone number.Normalized to E.164 - see Phone numbers.+14155550101

​
Field behavior

​
Domain derivation

  • If domain is blank, it’s taken from the email - jane.doe@acme.com → acme.com.
  • If domain is provided, that value is used as-is.
  • A domain that doesn’t 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 the product.
You enterStored asWhy
4155550101+14155550101No country code → the default +1 (North America) is added.
(415) 555-0101+14155550101Separators removed, +1 added.
14155550101+14155550101Recognized as a North American number that already includes the 1.
+14155550101+14155550101Already E.164 - kept as-is.
+44 7911 123456+447911123456International (+ present) - country code kept, separators removed.
1-800-FLOWERSrejectedContains letters.
555-0101rejectedToo few digits to be a valid number.
Numbers outside North America must include a + and their country code (e.g. +44…). Without a leading +, a number is assumed to be a 10-digit North American number and gets +1.

​
Addresses

An address is recorded whenever any address column has a value - a partial address (say, only locality and country) is fine, and the missing parts are left blank. If every address column is blank, no address is stored.

​
Run the import

The Import users via CSV dialog listing required columns externalId, username, email, firstName, lastName and optional columns domain, streetAddress, locality, region, postalCode, country, phone, with an area to choose or drag a CSV file.

Start the import

In Directory → Users, choose to import via CSV. The dialog shows the expected columns.

Choose your file

Select your CSV or drag it onto the upload area.

Upload and validate

Iru validates the whole file first. If it passes, the rows are accepted and your users are created or updated in the background. If validation fails, you stay in the dialog with a report to fix - nothing is imported.

Review the result

A successful upload reports how many users were staged and adds the import to your history, where you can confirm how each row landed.

​
Create vs. update - re-uploading

Users are matched on externalId within the csv source:
  • A new externalId creates a new user. New users are given the end-user role.
  • An existing externalId updates that user’s details from the row. Updating does not change their role or group memberships.
So you can re-upload a corrected or expanded CSV at any time to keep the imported users in sync. Within a single file, every externalId 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 happens in two stages. Until the file is fully accepted, nothing is imported.
The file itself can’t be processed - for example 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. You get a list of every problem, each 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:
LineColumnMessage
3emailis not a valid email address
5usernameis required
8phoneis not a valid phone number
9externalIdis duplicated in this file
Fix the listed rows and re-upload.
Once a file is accepted, rows are applied in the background. A row can still fail at this stage - for example an email that’s already in use by another user, or a value conflicting with a unique attribute. These apply errors are recorded against the import batch; each shows the row’s externalId and username, the error, and which batch it belongs to. Correct those rows and re-import them.

​
Example file

externalId,username,email,firstName,lastName,domain,streetAddress,locality,region,postalCode,country,phone
CSV-001,jane.doe,jane.doe@acme.com,Jane,Doe,acme.com,1 Market St,San Francisco,CA,94105,US,(415) 555-0101
CSV-002,john.roe,john.roe@acme.com,John,Roe,,500 Boylston St,Boston,MA,02116,US,+16175550102
CSV-003,amir.khan,amir.khan@acme.io,Amir,Khan,,,,,,,
CSV-004,mei.lin,mei.lin@acme.io,Mei,Lin,,,London,,EC1A 1BB,GB,+44 7911 123456
CSV-005,carlos.diaz,carlos.diaz@acme.com,Carlos,Diaz,acme.com,,,,,,3105550105
  • CSV-001 - every field provided; the phone normalizes to +14155550101.
  • CSV-002 - blank domain, so it’s derived as acme.com.
  • CSV-003 - only the required fields; no address or phone.
  • CSV-004 - a partial address and an international phone (+44…).
  • CSV-005 - phone only, with no country code → stored as +13105550105.

​
When to use HR sync instead

You can re-upload a CSV whenever your list changes, and Iru re-checks every row. For hands-off, continuous provisioning, connect your HR system as the authoritative record instead.
CSV importHR system sync
TriggerYou upload a fileRuns automatically on a schedule
Keeps current?When you re-uploadYes - re-syncs automatically
Create / updateBoth, matched on externalIdBoth, automatically
RemovalManualCan remove people as they’re offboarded
Best forInitial loads, ad-hoc additionsOngoing lifecycle automation
You can use both - many teams seed the directory with a CSV to get going, then connect their HR system to take over keeping everyone current. Setup is covered in Directory Sync.

​
Next steps

Connect your HR system

Automate creates, updates, and removals on a schedule.

Design your schema first

Decide required and unique attributes so imports land cleanly.

Manage individual users

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

Organize into groups

Turn your imported users into assignable groups.