Endpoints

Import users from CSV

Upload a CSV file, configure import options, and start processing immediately.

POST /api/import/csv

Authentication

Required. See Authentication.

Content type

Content-Type: multipart/form-data

Request body (multipart fields)

Field	Type	Required	Default	Description
file	file	Yes		CSV file to import. Field name must be file.
csvIdentifierColumn	string	Yes		Name of the CSV column used to identify users (e.g. user_id, email).
name	string	No	Auto-generated	Display name for the import in the Jimo dashboard.
description	string	No	null	Optional description for the import.
jimoIdentifier	string	No	ID	How Jimo matches users. Allowed values: ID, EMAIL.
enableAddUser	boolean	No	false	Create users that do not already exist in Jimo.
enableUpdateUser	boolean	No	true	Update existing users with values from the CSV.
createSegment	boolean	No	false	Create a segment containing all imported users.
allowNewProperties	boolean	No	true	Allow auto-creation of new custom attributes from CSV columns. Set to false to only update existing properties.

Example request

Send as multipart/form-data. Attach the CSV as the file field alongside the options below:

{
  "file": "<binary CSV file>",
  "csvIdentifierColumn": "user_id",
  "jimoIdentifier": "ID",
  "enableAddUser": true,
  "enableUpdateUser": true,
  "allowNewProperties": false,
  "name": "API import - June 2026"
}

Success response

Status: 200 OK Content-Type: application/json

{
  "importId": "3f2a1b4c-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "status": "IN_PROGRESS"
}

Field	Type	Description
importId	string (UUID)	Unique identifier of the launched import. Use it to poll status.
status	string	Initial import status. Typically IN_PROGRESS after a successful launch.

Import status values

Value	Description
DRAFT	Import created but not yet launched
IN_PROGRESS	Import is running
DONE	Import completed successfully
ERROR	Import failed

Error responses

Errors are returned as JSON with an HTTP 4xx or 5xx status code.

HTTP Status	Error code	Description
400	FILE_NOT_FOUND	No file was uploaded or the file field is missing
400	FILE_TOO_LARGE	File exceeds the maximum size allowed for your API credentials (default: 50 MB)
400	PROJECT_OWNER_NOT_FOUND	Project owner could not be resolved to launch the import
403	ACCESS_DENIED	Missing or invalid authentication (see home doc)
400	PROJECT_NOT_FOUND	No project is associated with the API credentials

Validation errors on body fields (e.g. missing csvIdentifierColumn, invalid jimoIdentifier) return 400 Bad Request with a standard NestJS validation error payload.

Get import status

Poll the progress and result of an import launched via the API.

GET /api/import/csv/status/:importId

Authentication

Required. See Authentication.

Path parameters

Parameter	Type	Required	Description
importId	string (UUID)	Yes	Import ID returned by POST /api/import/csv

Example request

{
  "method": "GET",
  "path": "/api/import/csv/status/3f2a1b4c-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "headers": {
    "Authorization": "Bearer <base64(client:secret)>"
  }
}

Success response

Status: 200 OK Content-Type: application/json

{
  "importId": "3f2a1b4c-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "status": "DONE",
  "name": "API import - June 2026",
  "startedAt": "2026-06-08T10:15:30.000Z",
  "endedAt": "2026-06-08T10:16:02.000Z",
  "totalRow": 1250,
  "totalRowProceed": 1250,
  "totalUserAdded": 340,
  "totalUserUpdated": 910,
  "totalUserErrored": 0,
  "error": null,
  "errorsUser": []
}

Field	Type	Description
importId	string (UUID)	Import identifier
status	string	Current status (DRAFT, IN_PROGRESS, DONE, ERROR)
name	string	Import name
startedAt	string (ISO 8601) | null	When processing started
endedAt	string (ISO 8601) | null	When processing ended
totalRow	number	Total rows in the CSV
totalRowProceed	number	Rows processed so far
totalUserAdded	number	Users created
totalUserUpdated	number	Users updated
totalUserErrored	number	Rows that failed
error	string | null	Global error message if the import failed
errorsUser	string[]	Per-row error messages

Error responses

HTTP Status	Error code	Description
403	ACCESS_DENIED	Missing or invalid authentication
404		Import not found or does not belong to the authenticated project

Recommended workflow

1. Call POST /api/import/csv with your CSV file and options.

2. Store the returned importId.

3. Poll GET /api/import/csv/status/:importId until status is DONE or ERROR.

4. Review totalUserAdded, totalUserUpdated, totalUserErrored, and errorsUser in the final response.

Imports launched through this API are flagged in the Jimo dashboard with an API badge.