Bulk import users from CSV

When to use this

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

bulkImportUserShown in the dashboard as “Bulk Import Users”. Keys with “Bulk Update User” are also accepted.

Uploading needs bulkImportUser, shown in the dashboard as Bulk Import Users. Keys with bulkUpdateUser (Bulk Update User) are also accepted, but give new keys the import permission. Reading the custom field job back needs getBulkUpdate as well. The traders are always created in the API key's community. Keep the key on your server.

02Behaviour#

03Request#

Headers#

Body#

Send multipart/form-data with the file in field data. The first line must be a header row. Column names are not case-sensitive.

Username,Email,First Name,Last Name,Country,Join Server,Customer ID,Funded At,Challenge Revenue
sample_trader,trader@example.com,Sample,Trader,Singapore,true,<brokerCustomerId>,2026-09-18T15:50:45.414Z,1250.50

Required columns:

• Username and Email.
• Your community's broker customer ID field, if it has one, by its display name or key. It must be filled in and unique.
• Any profile field your community makes compulsory: First Name, Last Name, Phone or Country.

Optional columns: First Name, Last Name, Phone, Country, Language, Role, Tag and Join Server. A missing column is read as empty.

• Username: 2 to 49 characters, letters, numbers, . and _, not starting or ending with . or _.
• First Name and Last Name: up to 49 characters.
• Phone: digits, optionally with a leading + and country code; spaces and dashes are allowed, letters are not.
• Country: the country's full name, such as Singapore. Language: the language name, such as English.
• Role and Tag: comma-separated. Each role must already exist in your community.
• Join Server: true makes the trader a member of your community straight away. Any other value, or no column, adds them as invited; they become a member when they set their password or join.

Custom field columns:

• Add a column for each custom field you want to fill, named by its display name or its key.
• Values follow the bulk update rules: numbers such as 1250.50, true or false for yes/no fields, and ISO 8601 for date-time fields, such as 2026-09-18T15:50:45Z. A date-time can include milliseconds or an offset such as +08:00; without an offset it is read as UTC.
• Number fields are written with overwrite. Add a <column>_op column with add or subtract to change that.
• An empty cell is skipped. A row with any invalid custom value skips all of that trader's custom values, but the trader is still created.
• Columns that are not a standard column or one of your custom fields are ignored.

Duplicates:

• A row is skipped if its email, username or customer ID already belongs to a trader, or appears earlier in the same file. Emails are compared without case, so Trader@Example.com in your file matches an existing trader@example.com.
• There is no row limit; the file can be up to 30 MB. Split a larger file and upload the parts one after another.

Send the body as multipart/form-data.

curl --request POST \
  --url https://api.returning.ai/v1/users/bulk-import \
  --header 'Authorization: Bearer <API_KEY>' \
  --form 'data=@traders.csv'

04Response#

A 200 returns only a confirmation that the import is queued. It has no job ID. Check a few traders with Get User Data, and follow the Bulk import custom fields job if your file had custom field columns.

{
  "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 )"
  }
}

05Errors#

Errors from the API key check, such as 401 and 403, carry the code in meta.code. Other errors from this endpoint have no code, so branch on the HTTP status. Problems inside the file never cause an error here; they show up on the import in API Logs and in its row file.

{
  "status": "fail",
  "message": "Uploaded file must be a CSV"
}

06Next step#