Import contacts (asynchronous)

POST

/contacts/import

curl --request POST \
  --url https://app.surveyrock.com/api/v1/contacts/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "contacts": [ { "email": "hello@example.com", "first_name": "example", "last_name": "example", "customFields": {} } ], "strategy": "skip", "list_id": "example", "start_workflows": true }'

• API v1 endpoints

Creates an import job for the contacts in the request body and returns at once with a job_id; poll GET /contacts/import/{jobId} for the result. Up to 1,000 contacts per request: send a larger list in several requests. New addresses are always created; strategy decides what happens to a contact that already exists: skip leaves it untouched, update_only fills only its empty fields, overwrite replaces its name and custom-field values with the ones sent. An address that is not a valid email, or is on the workspace’s suppression list, is not imported and is reported in the job’s result, not as an error on the request. Requires a plan with contact import (the same as the web import).

Authorizations

• bearerAuth
  contacts:write

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters

1 to 128 characters, chosen by the caller. A retry with the same key and body replays the first response instead of applying the write twice; the same key with a different body is a 409

Request Body^required

Media typeapplication/json

object

contacts

required

Array<object>

<= 1000 items

object

email

required

string format: email

first_name

string

<= 255 characters

last_name

string

<= 255 characters

customFields

Values keyed by the id of one of the workspace’s custom fields

object

strategy

required

What to do with a contact that already exists

string

Allowed values: skip update_only overwrite

list_id

A contact list of this workspace to add every imported contact to

string

nullable

start_workflows

Start the workflows that listen for a contact being added to list_id

boolean

default: true

Responses

202

Import job created. data holds job_id, status (pending) and total_rows.

400

list_id is not a contact list of this workspace

403

The plan does not include contact import (feature_locked)

422

The request is malformed: each error names the field

429

The workspace already has the maximum number of imports pending or running