Imports

Invite candidates from a CSV, TSV or Excel file.

Scope: candidates:import.

The import object

Field	Type
`id`	string	`imp_…`
`object`	`"import"`
`status`	string	`pending`, `processing`, `completed` or `failed`
`livemode`	boolean
`interviewer_id`	string or null
`file_name`	string
`format`	string	`csv`, `tsv` or `xlsx`
`mapping`	object	Field to header, for example `{ "email": "E-mail" }`
`headers`	string[]	The file's header row
`send_email`	boolean
`total_rows`, `valid_rows`, `error_rows`, `processed_rows`	integer
`has_error_file`	boolean
`error`	string or null	Why the import failed, when it did
`created_at`, `completed_at`	timestamp

Import candidates

POST /candidates/import takes multipart/form-data:

Part
`file`	required	CSV, TSV or XLSX, up to 10 MB and 5,000 rows. The file name's extension picks the parser.
`interviewer_id`	required	`int_…`
`mapping`	optional	JSON object of field to header. Fields you leave out are matched from the headers.
`send_email`	optional	Default `true`

Fields: email, name (or first_name and last_name), phone, external_id, tags, resume_url.

curl https://api.interviewer.heizen.tech/api/v1/candidates/import \
  -H "Authorization: Bearer $HEIZEN_API_KEY" \
  -H "Idempotency-Key: import-2026-10-01" \
  -F file=@candidates.csv \
  -F interviewer_id=int_… \
  -F 'mapping={"email":"E-mail","name":"Full name"}' \
  -F send_email=true

The response is the import, already committed and running, plus errors: the first 200 rows that will be skipped, each { row, email, code, message }. See Imports in the dashboard for the codes.

When the import finishes, Heizen sends import.completed.

List imports

GET /imports with limit and cursor.

Retrieve an import

GET /imports/{id}. Poll it, or wait for the event, to follow processed_rows.

Error file

GET /imports/{id}/error_file returns { "url": "…", "expires_at": "…" }, a one-hour link to a CSV of every skipped row with its reason. Returns 404 error_file_not_available when nothing was skipped.