Bulk import users from CSV

CSV user import

Queues creation of users from a CSV file. This route requires a community API key: send Authorization: Bearer <COMMUNITY_API_KEY>. An embedding access_id/access_key or widget token is not a community API key. Keep the key server-side.

Send multipart file field data. Required CSV headers are Username and Email; optional headers include First Name, Last Name, Phone, Country, ISO Country Code, Language, Role, Tag, Join Server and supported community custom fields. Community identity comes from the authenticated key; a multipart communityId does not select another community.

The public gateway path is /v1/users/bulk-import; the integration service path is /apis/v1/users/bulk-import. Keep the existing server/environment configured for your integration. The existing legacy category does not mean authentication is optional.

Legacy production permission is bulkUpdateUser. After the dedicated-permission rollout, bulkImportUser is accepted, while transition mode also accepts bulkUpdateUser. Community strict mode requires bulkImportUser; administrators must migrate the intended key grants before enabling strict mode.

HTTP200 means queued, not complete. The legacy response is

{"status":"success","message":"Bulk import user process is queued","data":{"message":"Bulk import user process is queued. You can check in Api Log ( community settings )"}}

. Inspect the community's ApiLog and result CSV for row outcomes. Never assume every accepted CSV row became a user. A custom-field follow-up has its own status and result, independent of the parent import.

Optional hardening rollout

These controls default OFF and require Returning.AI to enable the community's cohort on the updated deployment. With H5_INTAKE_IDEMPOTENCY enabled, optional Idempotency-Key (visible ASCII,1–255 bytes) identifies the same community/route/file/options for24 hours; a successful response adds data.jobId. Identical requests replay that job. Changed payload returns409 IDEMPOTENCY_CONFLICT; an active intake returns409 IDEMPOTENCY_KEY_IN_PROGRESS. Legacy incomplete reservations may require operator repair. Do not assume idempotency when the control is OFF or after expiry; inspect ApiLogs before retrying an uncertain request.

Flagged import validation can normalize emails/usernames, reject invalid/duplicate rows, and report unknown/invalid custom fields as separate warnings. These behaviors are not blanket changes to communities outside the enabled cohort. Missing setup-password templates do not establish email delivery; a completed import means user processing finished, not that a recipient received email.

Errors

400 missing/non-CSV/invalid upload;401 missing, invalid or expired community key;403 insufficient permission;409 conditional idempotency conflict/in-progress/repair-required;500 intake persistence/upload failure. Keep keys and user data out of client-side code and support logs.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

"status": "success", "message": "Bulk import user process is queued", "data": { "message": "Bulk import user process is queued. You can check in Api Log ( community settings )" } }

CSV user import

Optional hardening rollout

Errors

Request

Responses

Bulk import users from CSV

CSV user import#

Optional hardening rollout#

Errors#

Request

Responses

CSV user import

Optional hardening rollout

Errors