Bulk importing users

Qorionix can create many user accounts in one request, from a CSV file or from JSON. This article documents the format precisely, because an import that half-works is worse than one that fails cleanly and you will want to know which you got.

For a single person, Who actually needs a Qorionix account and the Invite dialog remain the more direct path when you only need to add one or two people — though see What an invited user actually receives before you rely on it, since inviting somebody today does not email them anything. A non-invited bulk import, by contrast, sets a real password yourself and produces an account that works immediately with no delivery step at all — see the note on invited: false below.

Who can run an import

Both import endpoints require the users.write permission, which of the built-in roles only admin holds. A member or viewer attempting an import receives:

That is the standard denial across the whole platform. The permission model explains where it comes from and how to tell which permission was missing.

The CSV format

The file is sent as the raw body of the request. It is not a multipart file upload, which matters if you are scripting it — a tool that wraps the file in a form will produce a header row that is not a header row.

• The first line must be a header row. Columns are located by name, not by position, so the order is irrelevant.
• Column names are matched case-sensitively. Email is not email. A file exported from a spreadsheet with capitalised headings will be rejected.
• email and password are required. first_name and last_name are optional and are simply left blank if the column is absent.
• Any other column is ignored. You can leave a department or an employee number in the file; nothing reads it.

email,password,first_name,last_name
[email protected],Xq7!vetRoad2Loop,Anna,Kowalska
[email protected],Bramble#94Kestrel,Tom,Byrne
[email protected],Trellis!Harbour38,Sade,Okafor
[email protected],Quill4?Lantern-Bay,Payroll,Review

Column order does not matter, so this file is equally valid and imports the same four people:

password,email
Xq7!vetRoad2Loop,[email protected]
Bramble#94Kestrel,[email protected]
Trellis!Harbour38,[email protected]
Quill4?Lantern-Bay,[email protected]

The JSON format

The JSON endpoint takes an array of the same four fields, plus one flag.

{
  "users": [
    { "email": "[email protected]",
      "password": "Xq7!vetRoad2Loop",
      "first_name": "Anna", "last_name": "Kowalska" }
  ],
  "invited": false
}

Setting invited to true creates each account in the STAGED state with an unguessable placeholder password, so the person must set their own before they can sign in. That is the safer of the two shapes. It comes with a wrinkle worth naming: the row is still rejected if the password field is empty, even though an invited account never uses the value. Put a throwaway string in the field. It is discarded.

Row limits

One thousand users per batch, but the two endpoints enforce it differently and the difference is dangerous.

If you are importing more than a thousand people from CSV, split the file yourself and reconcile the counts. There is no size limit on the request body, only a row limit, so a large file will be accepted and quietly cut.

The exact error messages

Two kinds of error exist and they behave differently. A request-level error rejects the whole batch. A row-level error skips one row and lets the rest through.

Row-level errors are collected into an errors array in the response and do not stop the batch. The import is partial-success: good rows are created and stay created even when other rows fail. There is no transaction and no rollback, so a half-imported file leaves half the accounts in place.

A successful call always returns HTTP 200, whatever the mix of successes and failures, with this shape:

{
  "created": 47,
  "failed": 3,
  "errors": ["[email protected]: user email [email protected]: already exists"],
  "user_ids": ["..."]
}

Duplicates

Email addresses are unique across the platform. A row whose address already belongs to an account fails that one row and leaves the existing account completely untouched — nothing is overwritten, no password is reset, no name is changed. Re-running the same file is therefore safe in the narrow sense that it will not damage what already exists; it will simply report every row as failed.

Duplicates within one file behave the same way: the first occurrence is created, the second fails against the first. Order in the file decides which one wins, and the file is processed top to bottom.

What you cannot set through an import

Several fields are fixed by the importer and cannot be supplied in the file. Every account created by a non-invited import is active, marked as having a verified email address, typed as EMPLOYEE, given the status ACTIVE, and assigned the fixed role member — every imported user gets the same role, whatever the file says. You cannot set a different role, a group, a profile attribute or an organisation through the import. If you need any of those, the import will not save you the work — you will be editing every account afterwards anyway.

What to do next

1. What an invited user actually receives — read this before choosing Invite over a one-row import for a single person.
2. Users and the directory — what a user record holds.
3. Groups and automatic membership — how to organise people once they are in.