Skip to main content
POST
Add contacts to a list

Authorizations

Authorization
string
header
required

An API key (utk_live_...) or an app's OAuth access token (uto_...).

Headers

Idempotency-Key
string

Any 1 to 255 printable ASCII characters, without a space at either end. The answer to the first request with a key is kept for 24 hours per credential: the same request again gets it back (Idempotent-Replayed: true), another request with the key is 409 PUB-002-002, and while the first still runs 409 PUB-002-003. A server error is not kept, and a request that never answered frees its key after 2 minutes: a retry with the key then runs again.

Maximum string length: 255

Path Parameters

listId
string<uuid>
required

A contact list id.

Body

application/json
contactIds
string<uuid>[]
required

Contact ids, 1 to 500.

Required array length: 1 - 500 elements

Response

What changed.

added
integer
required

Contacts put on the list.

skipped
integer
required

Ids sent that were already on the list or aren't contacts of the organization.

Last modified on November 8, 2026