---
title: "Import contacts from CSV"
method: POST
path: "/v1/contacts/import"
tags: ["Contacts"]
---

# Import contacts from CSV

`POST /v1/contacts/import`

## Request

- Base URL: `https://api.volanea.com`
- URL: `https://api.volanea.com/v1/contacts/import`
- Auth: HTTP bearer

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.

## Request body

- object
  - `csv` string, required: 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.
  - `dedupe` 'update' | 'skip': What to do when an email already exists.

## Response `202`

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

- object
  - `importJobId` string, required: Poll `GET /v1/contacts/import/{id}` with this.
  - `status` 'queued', required
  - `total` integer, required: Data rows detected (header excluded). Nothing has been imported yet.

## Other responses

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

---

[API](https://skmtc.dev/volanea/apis/volanea-api.md) · [All operations](https://skmtc.dev/volanea/apis/volanea-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volanea/apis/volanea-api/revisions/9e187ae84fda?raw)