Contacts

List contacts

GET/api/v1/contacts

GET /contacts
curl -X GET 'https://www.unitpost.com/api/v1/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "id_123",
      "email": "customer@example.com",
      "phone": "string",
      "first_name": "string",
      "last_name": "string",
      "unsubscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z",
      "unsubscribe_reason": "USER",
      "custom_fields": {},
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of the contacts in your workspace, newest-first and cursor-paginated. Each row includes the contact's core fields, its SMS number (phone) and any custom field values. Narrow the list with q (email, first or last name, and 3+ digits of a phone number), status, phone, segment_id (members of a segment; also requires segments:read) and, for a static segment, segment_subscription. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. Use a contact's id (or email) with Retrieve a contact for the full record, add contacts with Create a contact, or bring a list in bulk with Start an async contact import. Requires the contacts:read capability.

Parameters8 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
qstring · querySearch email, first and last name (case-insensitive); with 3 or more digits it also matches the SMS number. At most 200 characters.
statusstring · query`subscribed` or `unsubscribed`: the contact-level marketing opt-out.
phonestring · query`has`: contacts with an SMS number; `none`: without one.
segment_idstring · queryOnly members of this segment: a static segment's members, or the contacts a dynamic segment's filter matches. Also requires `segments:read` (without it, or for an unknown segment, the filter is ignored with a warning; refused under `Unitpost-Strict`).
segment_subscriptionstring · queryWith a static `segment_id`: `subscribed` or `opted_out` of that segment's sends. A dynamic segment has no per-segment opt-out (422).
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200401403404422503

Create a contact

POST/api/v1/contacts

POST /contacts
curl -X POST 'https://www.unitpost.com/api/v1/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace"
  }'
Response · 200
{
  "object": "contact",
  "id": "id_123",
  "email": "customer@example.com",
  "phone": "string",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "unsubscribe_reason": "USER",
  "custom_fields": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Add a single contact to your workspace. Set an email plus any standard or custom field values, and optionally its SMS number (phone). A number is contact data, not consent: record SMS consent with Record SMS consent. Custom fields must already exist (define them with Create a custom contact field). Emails are unique per workspace, so creating one that already exists returns 409 — use Update a contact to change an existing contact, or Start an async contact import to add many at once. A sync that can't know which of the two it is can send update_if_exists: true: the contact that already has the email is updated with the fields in the body instead of the 409, and the response is 200 rather than 201. Requires the contacts:write capability.

Request body7 fields
FieldTypeDescription
emailrequiredstring—
phonestring | null—
first_namestring—
last_namestring—
unsubscribedboolean—
custom_fieldsobject—
update_if_existsboolean`true` updates the contact that already has this email instead of answering `409`: the fields you send are merged onto it (what you leave out is untouched, and `custom_fields` merges key by key), and the response is `200` rather than the `201` of a real create. Default `false`: a duplicate email is a `409`. It is not a way around an opt-out — `unsubscribed: false` on a suppressed address is still refused.
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200201401409422

Export contacts

POST/api/v1/contacts/export

POST /contacts/export
curl -X POST 'https://www.unitpost.com/api/v1/contacts/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "subscribed"
  }'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Export contacts to a CSV file, as the Contacts page's Export does: every contact, or the ones the list's filters match (q, status, phone, segment_id, segment_subscription, as on List contacts). It runs as a background job: follow it with Retrieve a job, then fetch the file with Download a job's file. One export runs at a time: another while it runs is a 409 job_in_progress naming it (Location). segment_id also needs segments:read. Requires the contacts:read capability.

Request body5 fields
FieldTypeDescription
qstringFree text: email, first and last name, and with 3+ digits the SMS number.
statusenumsubscribed | unsubscribed—
phoneenumhas | none—
segment_idstringMembers of this segment. Also needs `segments:read`.
segment_subscriptionenumsubscribed | opted_outWith a static `segment_id`: its per-segment opt-out.
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422429502

Set a field on many contacts

POST/api/v1/contacts/set-field

POST /contacts/set-field
curl -X POST 'https://www.unitpost.com/api/v1/contacts/set-field' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Set one custom field to the same value on many contacts, as the Contacts page's Set field does: the contacts you list (contact_ids or emails, up to 1,000, each a contact of this workspace) or every member of a segment (segment_id, however many; also needs segments:read). Send exactly one. key names a field that exists (Create a custom contact field); value is typed against it the way an import types it, and null clears it. With only_empty: true a contact that has its own value keeps it (a contact that only shows the field's default_value has none, so it is filled). Each contact whose value changes gets a contact.updated webhook (changed_fields) and an activity row naming your key; one that already has the value is left as it is. Subscriptions, topics and SMS consent are never touched. It always runs as a background job (202, Location); follow it with Retrieve a job. Listed contacts are checked first: the first that isn't one of yours is a 404 naming it (details), and nothing starts. One bulk operation runs per field at a time, and five bulk contact edits per workspace (409 job_in_progress). Starting one counts against a limit of 30 bulk contact edits a minute per workspace by default (a 429 started nothing; retry after Retry-After). Pass an Idempotency-Key so a retry answers the same job instead of starting another. To give different contacts different values, update each with Update a contact or import them with Start an async contact import. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body6 fields
FieldTypeDescription
keyrequiredstringThe custom field's key (`plan`). It must exist: create it with POST /contact-fields first.
valuerequiredstring | number | boolean | nullThe value, typed against the field the way an import types it: a number field takes `42` or `"42"`, a boolean `true` / `"yes"`, a date an ISO 8601 date. `null` clears the field.
only_emptybooleanDefault false: overwrite every value. True: set it only where the contact has no value of its own (the key is missing or null; a contact that shows the field's default has none). Not with `value: null`.
contact_idsstring[]Contacts of this workspace (`con_…`), up to 1,000.
emailsstring[]Contacts of this workspace by email address, up to 1,000.
segment_idstringEvery member of this segment (`seg_…`), however many. Also needs `segments:read`.
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422429502

Retrieve a contact

GET/api/v1/contacts/{id}

GET /contacts/{id}
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "contact",
  "id": "id_123",
  "email": "customer@example.com",
  "phone": "string",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "unsubscribe_reason": "USER",
  "custom_fields": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single contact and all of its field values. The {id} path segment accepts either the contact's id or its email address, so you can look a contact up without storing our id. Change it with Update a contact, or see which subscription topics it's opted into with List a contact's topic subscriptions. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a contact

PATCH/api/v1/contacts/{id}

PATCH /contacts/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/contacts/con_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "unsubscribed": true
  }'
Response · 200
{
  "object": "contact",
  "id": "id_123",
  "email": "customer@example.com",
  "phone": "string",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "unsubscribe_reason": "USER",
  "custom_fields": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a contact's standard or custom field values. Top-level fields you omit are left as-is, but custom_fields REPLACES the contact's whole map: read the contact first and send every key you want to keep. phone sets the contact's SMS number (consent is recorded separately); phone: null removes every SMS number it has, with Unitpost-Strict: true (without it the numbers are kept and Unitpost-Warning says so). Unknown keys are ignored. The {id} accepts a contact id or email. To manage a contact's subscription preferences instead, use Set a contact's topic preference. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body5 fields
FieldTypeDescription
phonestring | null—
first_namestring | null—
last_namestring | null—
unsubscribedboolean—
custom_fieldsobject—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200401404409422

Delete a contact

DELETE/api/v1/contacts/{id}

DELETE /contacts/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/contacts/con_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Permanently delete a contact and its field values. This also removes the contact from every segment it belonged to, including the audience of any unfinished campaign. To stop mailing someone without deleting them, unsubscribe them from a topic with Set a contact's topic preference or add them to your suppression list instead. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404

List a contact's addresses

GET/api/v1/contacts/{id}/addresses

GET /contacts/{id}/addresses
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/addresses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_address",
      "channel": "string",
      "address": "string",
      "primary": false,
      "status": "queued",
      "country": "string",
      "verified_at": "2026-01-01T00:00:00.000Z",
      "consented_at": "2026-01-01T00:00:00.000Z",
      "consent_source": "string",
      "consent_purpose": "string",
      "carrier_opt_out_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Every address the contact can be reached at: its email addresses and SMS numbers, each with its status and, for a number, its SMS consent state. The contact's phone is its primary number; this lists all of them, including numbers the person texted in from. The full consent history is Get a contact's SMS consent. The {id} accepts a contact id or email. Not paginated. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
channelrequiredstring`email` for an email address, `sms` for a phone number.
addressrequiredstringThe email address, or the phone number in E.164.
primaryrequiredbooleanThe address sends use for this channel.
statusrequiredstring`active`, or why it can't be used (e.g. `opted_out`, `bounced`).
countryrequiredstring | nullISO country of a phone number.
verified_atrequiredstring | null—
consented_atrequiredstring | nullWhen SMS consent was recorded (see `/contacts/{id}/sms-consent`).
consent_sourcerequiredstring | null—
consent_purposerequiredstring | null—
carrier_opt_out_atrequiredstring | nullWhen the carrier last refused a text to this number because it opted out at the carrier. Not a consent record.
created_atrequiredstring—
200401403404

List a contact's recent messages

GET/api/v1/contacts/{id}/activity

GET /contacts/{id}/activity
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/activity' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_activity",
      "message_id": "message_123",
      "channel": "string",
      "direction": "outbound",
      "subject": "Welcome to Acme",
      "status": "queued",
      "campaign_id": "campaign_123",
      "created_at": "2026-01-01T00:00:00.000Z",
      "sent_at": "2026-01-01T00:00:00.000Z",
      "error": "string",
      "error_code": "string"
    }
  ]
}

The contact's most recent messages across channels, newest first: the emails sent to them, and texts both ways. Emails also require emails:read and texts sms:read; without one, those rows are left out. Returns up to limit (1–100, default 25) with no cursor: for the full history page List sent emails or List SMS messages with contact_id. The {id} accepts a contact id or email. Requires the contacts:read capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryHow many recent messages (1–100, default 25).
Response · 200 fields11 fields
FieldTypeDescription
objectrequiredstring—
message_idrequiredstringAn email (`email_…`) or text (`sms_…`) id; read it with its own get operation.
channelrequiredstring`email` or `sms`.
directionrequiredenumoutbound | inbound—
subjectrequiredstring | nullAn email's subject, or the start of a text.
statusrequiredstringThe message's `status` as its own object reports it (`GET /email/{id}`, `GET /sms/{id}`).
campaign_idrequiredstring | null—
created_atrequiredstring—
sent_atrequiredstring | null—
errorrequiredstring | nullTexts only: why it wasn't delivered, in plain words.
error_coderequiredstring | null—
200401403404422

List a contact's segments

GET/api/v1/contacts/{id}/segments

GET /contacts/{id}/segments
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_segment",
      "segment_id": "segment_123",
      "name": "Example",
      "type": "static",
      "subscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The segments the contact is in: static segments by membership, with its per-segment opt-out (subscribed), and dynamic segments whose filter it matches now. Not paginated. From the segment's side, see List segment members. The {id} accepts a contact id or email. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
segment_idrequiredstring—
namerequiredstring—
typerequiredenumstatic | dynamicA dynamic segment's members come from its filter; they can't be added or removed by hand.
subscribedrequiredbooleanWhether this segment's sends reach the contact (a static segment can be opted out of on its own).
unsubscribed_atrequiredstring | null—
200401403404503

List contact imports

GET/api/v1/contacts/imports

GET /contacts/imports
curl -X GET 'https://www.unitpost.com/api/v1/contacts/imports' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "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"
    }
  ]
}

Retrieve a list of your bulk contact-import jobs, newest-first and cursor-paginated. Each row is a reference to one import and its current progress. Start a new one with Start an async contact import, or drill into a single job with Retrieve a contact import. Requires the contacts:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
200401422

Start an async contact import

POST/api/v1/contacts/imports

POST /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 '{ }'
Response · 202
{
  "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
FieldTypeDescription
contactsrequiredobject[]—
update_existingbooleanUpdate 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
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
202401422502

Retrieve a contact import

GET/api/v1/contacts/imports/{id}

GET /contacts/imports/{id}
curl -X GET 'https://www.unitpost.com/api/v1/contacts/imports/imp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "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"
}

Retrieve a bulk import job by id to check its status and per-row results — how many contacts were created, updated, or skipped, and why any rows failed. Poll this while an import runs. Start one with Start an async contact import. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Cancel a contact import

POST/api/v1/contacts/imports/{id}/cancel

POST /contacts/imports/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/contacts/imports/imp_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "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"
}

Stop a pending or processing import job. A running import stops at its next chunk of rows; contacts it already imported are kept. The job's status becomes canceled. A job that has already finished returns 409. Check its progress first with Retrieve a contact import. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409

Retry a contact import

POST/api/v1/contacts/imports/{id}/retry

POST /contacts/imports/{id}/retry
curl -X POST 'https://www.unitpost.com/api/v1/contacts/imports/imp_123/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "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"
}

Re-run a failed import from the rows stored on the job, without uploading them again. Rows that landed in the failed run are skipped as duplicates, so a retry only adds what is missing (an update_existing import keeps that setting; changes already made count as skipped). Any other state is a 409 (a second retry while the first runs finds the job pending), and so is a job whose rows are no longer kept: start a new import. Same rate limit as starting an import. No body; track it with Retrieve a contact import. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 202 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
202400401403404409422429502

Search docs and guides

Search the docs and product guides.