Import contacts from CSV

POST/v1/contacts/import

Secret key — sk_… or sk_test_… · Base URL https://api.volanea.com

CSV with a header row; an email column is required. firstName, lastName, subscribed, and locale columns map to contact fields; any other column becomes a custom data field.

Asynchronous. This answers 202 with a job id as soon as the header row validates; the rows are imported by a background worker. It does NOT return final counts — poll GET /v1/contacts/import/{id} until status is done or failed. Only the malformed-CSV cases (no header, no email column) are decided synchronously, as 422.

Body

Required · application/json

csvstringrequired
The CSV content. Max 8,000,000 characters — the whole file is stored on the job document, and Mongo caps a document at 16 MB.
dedupeenum
What to do when an email already exists.
updateskip

Response

Import accepted and queued. No contact has been written yet.

importJobIdstringrequired
Poll `GET /v1/contacts/import/{id}` with this.
statusenumrequired
queued
totalintegerrequired
Data rows detected (header excluded). Nothing has been imported yet.

Errors

Every failure returns the standard envelope — branch on `code`, never on the wording of `error`.

401Missing or invalid API key.
422Request validation failed (code `validation_error`, 422).

Request

curl https://api.volanea.com/v1/contacts/import \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "<csv>",
    "dedupe": "update"
  }'

Response

202 · application/json

{
  "success": true,
  "data": {
    "importJobId": "<importJobId>",
    "status": "queued",
    "total": 1
  }
}

92 endpoints · OpenAPI document