Bulk Create / Update Contacts

Upsert up to 1,000 contacts in a single call, processed asynchronously.

POSThttps://api.audienceful.com/v2/people/bulk

curl --location --request POST 'https://api.audienceful.com/v2/people/bulk' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data-raw '{
    "people": [
        { "email": "a@example.com", "tags": ["import"], "notes": "", "extra_data": { "plan": "pro" } },
        { "email": "b@example.com" }
    ]
}'

{
  "operation_id": "task-abc123",
  "operation_url": "https://api.audienceful.com/v2/operations/task-abc123",
  "status": "pending",
  "accepted": 2
}

Requires the people:write scope. This endpoint accepts up to 1,000 contacts per call and processes them asynchronously — it returns immediately with an operation_id you can poll for completion. Like the single Create a Contact endpoint, contacts are keyed by email: any email that already exists is merged with the supplied data (there is no skip-existing mode).

Body

peoplearrayrequired

The contacts to create or merge (at least one, at most 1,000).

Properties

emailstringrequired

The contact's email address.

tagsarray[string]

A list of tag names to apply. Tags that don't exist are created.

notesstring

Notes associated with this contact.

extra_dataobject

Custom field values, keyed by each field's data_name (the same shape used by the single-contact endpoints).

Response

Returns 202 Accepted.

operation_idstring

The id of the async operation.

operation_urlstring

The full URL of the operation — poll it to watch the batch progress from pending → processing → succeeded.

statusstring

The operation's initial status, pending. Poll the operation to see it move as the batch is processed.

acceptednumber

The number of contacts accepted for processing.