users_users_import
Bulk-import end users into this product, up to 500 rows per call — batch client-side beyond that.
Bulk-import end users into this product, up to 500 rows per call — batch client-side beyond that. Hashes only: pass `password.phcHash` for an argon2id PHC string, or `password.foreignHash` + `foreignHashAlgo` (bcrypt/argon2/pbkdf2/scrypt) for a hash from the system you are migrating off. A foreign hash is stored INERT — nothing verifies it until sign-in, when it is checked once and rehashed — so set `requiresReset: true` on rows whose source hash you do not trust. IDEMPOTENT by canonical identifier: a row whose email already exists VERIFIED in this product is skipped, not duplicated, so re-running the same file is safe. Imported identifiers default to verified (unlike users_users_create) — pass `verified: false` per identifier for addresses the source system never confirmed. Returns a PER-ROW report ({row, status, userId, reason}) plus counts: one malformed row never fails the batch. Emits ONE batch event (`users/user.imported`, with counts) rather than a per-user created event, and writes ONE audit row. Rows may be CONTACTS (`kind: "contact"` — known to the Product, no credential, never signed in); a contact row carrying `password`, `waitlisted` or `requiresReset` comes back as a FAILED ROW with `contact_cannot_hold_credentials`, never as a rejected batch. The result and the `users/user.imported` event carry a `contacts` count of the rows actually created. Contact channels (`phone`, `telegram`, `linkedin`, `x`) import as UNVERIFIED regardless of this tool's `verified: true` default — nothing here can prove a phone or a handle, so there is no confirmation to carry over. A row whose channel value does not fit its type comes back as a FAILED ROW with `invalid_identifier`, never as a rejected batch.
Behavior
- HTTP
POST /users/users/import
Arguments
Name | Type | Required | Description |
|---|---|---|---|
users | array | • | The users to import, at most 500 per call — batch client-side beyond that. Each row: identifiers (email), optional profile, optional password HASH, optional flags. |
Response
Field | Type | Always | Description |
|---|---|---|---|
failed | integer | • | How many rows could not be imported at all. |
created | integer | • | How many users were created. |
results | array | • | One row per submitted row, in the order you sent them. |
skipped | integer | • | How many rows were passed over — an address already in the directory, typically. |
contacts | integer | • | How many of the CREATED users were contacts (`kind: 'contact'`). A row that was skipped or failed is not counted. |
requested | integer | • | How many rows you submitted. |
Try it
Bulk-import end users into this product, up to 500 rows per call — batch client-side beyond that.