Start an async contact import
POST/api/v1/contacts/imports
curl -X POST 'https://www.unitpost.com/api/v1/contacts/imports' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'User-Agent: my-app/1.0' \
-H 'Content-Type: application/json' \
-d '{ }'{
"object": "contact_import",
"id": "id_123",
"status": "pending",
"total": 1,
"imported": 0,
"updated": 0,
"skipped": 0,
"failed": 0,
"invalid": [
{
"row": 0,
"reason": "string"
}
],
"error": "string",
"update_existing": false,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Import a batch of contacts (up to 5,000 per request) in the background. The call returns immediately with an import job you poll for progress and per-row results — new contacts are created and, by default, existing ones (matched by email) are skipped, not changed. To fill names and custom fields onto contacts you already have, send update_existing: true: each existing contact gets the names its row carries and its custom_fields merged key by key, and is counted in updated. An import never changes an existing contact's subscription. Contacts that already exist don't count against your plan's contact limit. Track it with Retrieve a contact import, or see all your imports via List contact imports. To add a single contact synchronously, use Create a contact. Requires the contacts:write capability.
Request body2 fields
| Field | Type | Description |
|---|---|---|
contactsrequired | object[] | — |
update_existing | boolean | Update contacts that already exist instead of skipping them. A row whose email belongs to a contact sets the `first_name` and `last_name` it carries (a blank one is ignored) and merges its `custom_fields` key by key: keys the row leaves out keep their values. The contact's subscription is never changed (`unsubscribed` applies only to contacts the import creates). Counted in `updated`; a row that changes nothing is counted in `skipped`. Default `false`: existing contacts are skipped. |
Response · 202 fields13 fields
| Field | Type | Description |
|---|---|---|
objectrequired | string | — |
idrequired | string | — |
statusrequired | enumpending | processing | completed | failed | canceled | — |
totalrequired | number | — |
importedrequired | number | — |
updatedrequired | number | — |
skippedrequired | number | — |
failedrequired | number | — |
invalidrequired | object[] | — |
errorrequired | string | null | — |
update_existingrequired | boolean | — |
created_atrequired | string | — |
updated_atrequired | string | — |