Contact lists

The contact lists a campaign sends to (audience.list), and the contacts in them. How-to: Run a campaign, Keep contacts.

Generated from /openapi/v1.json; interactive version: API reference.

Endpoints

method	path	what it does	success
GET	/v1/lists	List contact lists, for a campaign’s audience.list	200
POST	/v1/lists	Create a contact list, with its contacts	201
GET	/v1/lists/{id}	Read a contact list	200
PATCH	/v1/lists/{id}	Rename a contact list	200
DELETE	/v1/lists/{id}	Delete a contact list no campaign is using	200
GET	/v1/lists/{id}/contacts	List the contacts in a list	200
POST	/v1/lists/{id}/contacts	Add contacts to a list	200
DELETE	/v1/lists/{id}/contacts/{contact}	Take one contact out of a list	200

GET /v1/lists

List contact lists, for a campaign’s audience.list.

Parameters

name	in	type	description
limit	query	integer 1–200	Page size, 1 to 200 (default 50).
after	query	string	The previous page’s next_cursor.

Answers 200 with ContactListList. Errors use the error envelope; common codes: contact lists, lists.

POST /v1/lists

Create a contact list, with its contacts.

Makes a list (source: api) and imports contacts into it through the same import as a campaign’s audience.contacts: a number a contact already has reuses that contact, never a second one. Each phone is stored for SMS, calls and WhatsApp alike, so the list works for a campaign on any channel. Storing a number is not consent: opt-outs stay on the number. contact_ids adds contacts you already have, by id, as POST /v1/lists/{id}/contacts does; an id that is not one of your live contacts is skipped and named in import.errors. A request that names people (contacts and/or contact_ids) and would add none of them is 400 empty_audience_input and creates no list. Pass the list’s id as a campaign’s audience.list.

Parameters

name	in	type	description
idempotency-key	header	string ≤ 255 chars	Send one with every create. A retry with the same key makes no second list: it answers the first one as it is now, with the first import. Rules: Idempotency.

Request body: ContactListCreate.

Answers 201 with ContactListWithImport. Errors use the error envelope; common codes: contact lists, lists.

GET /v1/lists/{id}

Read a contact list.

Parameters

name	in	type	description
id	path	string, required	The list’s cl-… id or UUID.

Answers 200 with ContactList. Errors use the error envelope; common codes: contact lists, lists.

PATCH /v1/lists/{id}

Rename a contact list.

Changes the list’s name; nothing else. Any list GET /v1/lists shows can be renamed, whatever its source: a campaign list keeps its source and is still removed with its campaign’s draft. The same name is no change. A rename is idempotent, so no Idempotency-Key is needed (one sent is ignored). Add contacts with POST /v1/lists/{id}/contacts.

Parameters

name	in	type	description
id	path	string, required	The list’s cl-… id or UUID.

Request body: ContactListUpdate.

Answers 200 with ContactList. Errors use the error envelope; common codes: contact lists, lists.

DELETE /v1/lists/{id}

Delete a contact list no campaign is using.

The list disappears from GET /v1/lists and can no longer be an audience.list. Its contacts, and their opt-outs, stay. Refused while a draft, queued, running or paused campaign uses it; a finished campaign does not keep it.

Parameters

name	in	type	description
id	path	string, required	The list’s cl-… id or UUID.

Answers 200 with the object below. Errors use the error envelope; common codes: contact lists, lists.

field	type	description
id	string, required
object	string, required always contact_list
deleted	boolean, required always true

Example: see Run a campaign.

GET /v1/lists/{id}/contacts

List the contacts in a list.

Parameters

name	in	type	description
id	path	string, required	The list’s cl-… id or UUID.
limit	query	integer 1–200	Page size, 1 to 200 (default 50).
after	query	string	The previous page’s next_cursor.

Answers 200 with ContactListMemberList. Errors use the error envelope; common codes: contact lists, lists.

POST /v1/lists/{id}/contacts

Add contacts to a list.

Imports contacts into the list, as POST /v1/lists does, and adds contact_ids, contacts you already have. Answers the list and what the import did: an id that is not one of your contacts is skipped and named in import.errors.

Parameters

name	in	type	description
id	path	string, required	The list’s cl-… id or UUID.
idempotency-key	header	string ≤ 255 chars	Send one with every add. A retry with the same key imports nothing twice: it answers the list as it is now, with the first import. Rules: Idempotency.

Request body: ContactListAddContacts.

Answers 200 with ContactListWithImport. Errors use the error envelope; common codes: contact lists, lists.

DELETE /v1/lists/{id}/contacts/{contact}

Take one contact out of a list.

contact is the contact’s ct-… id or UUID, or a phone number in E.164 (URL-encode the + as %2B). The contact itself, its numbers and its opt-outs are untouched.

Parameters

name	in	type	description
id	path	string, required	The list’s cl-… id or UUID.
contact	path	string, required	ct-…, a UUID, or E.164.

Answers 200 with the object below. Errors use the error envelope; common codes: contact lists, lists.

field	type	description
id	string, required
object	string, required always contact_list_member
list	string, required
deleted	boolean, required always true

Example: see Run a campaign.

Objects

ContactListList

field	type	description
object	string, required always list
data	array of ContactList, required
has_more	boolean, required
next_cursor	string or null, required	Pass as after for the next page; null on the last.

Example: see Finding ids.

ContactList

field	type	description
id	string, required	cl-…: pass as audience.list.
object	string, required always contact_list
uuid	string, required
name	string, required
source	string, required api, dashboard, campaign	Who made it: api (POST /v1/lists), campaign (imported from a campaign’s inline contacts or csv; removed when that campaign is deleted, unless another campaign uses it), dashboard (the dashboard, a CSV upload or Octo).
contacts	integer, required	How many contacts the list holds (deleted contacts are not counted).
created_at	string or null, required

Example: see Finding ids.

ContactListCreate

field	type	description
name	string, required 1–200 chars
contacts	array of objects ≤ 10,000 items	Up to 10,000 rows, the same rows as a campaign’s audience.contacts. Each phone is stored for SMS, calls and WhatsApp alike (one contact per number), so the list works for a campaign on any channel; that is not consent: opt-outs stay on the number. Leave it out for an empty list; an empty array is 400 empty_audience_input.
contacts[].phone	string, required pattern ^\+[1-9]\d{6,14}$	Same as CampaignAudience.contacts[].phone.
contacts[].name	string ≤ 200 chars	Same as CampaignAudience.contacts[].name.
contacts[].email	string ≤ 320 chars
contacts[].company	string ≤ 200 chars
contacts[].attributes	map of string to string or number or boolean	Custom fields, readable as {{contact.<key>}} in variables.
contact_ids	array of string ≤ 1,000 items; each ≤ 64 chars	Up to 1,000 contacts you already have, by ct-… id or UUID, as on POST /v1/lists/{id}/contacts. One that is not a contact of this workspace (or was deleted) is skipped and named in import.errors. With contacts, both are added. A request that names people and would add nobody is 400 empty_audience_input and creates no list; an empty array is 400 empty_audience_input too.

{
  "name": "October open house",
  "contact_ids": [
    "ct-00000000a1"
  ]
}

ContactListUpdate

Rename a list. Its contacts are changed with POST /v1/lists/{id}/contacts.

field	type	description
name	string, required 1–200 chars	The list’s new name (1 to 200 characters, trimmed).

{
  "name": "November open house"
}

ContactListWithImport

field	type	description
id	string, required	cl-…: pass as audience.list.
object	string, required always contact_list
uuid	string, required
name	string, required
source	string, required api, dashboard, campaign	Who made it: api (POST /v1/lists), campaign (imported from a campaign’s inline contacts or csv; removed when that campaign is deleted, unless another campaign uses it), dashboard (the dashboard, a CSV upload or Octo).
contacts	integer, required	How many contacts the list holds (deleted contacts are not counted).
created_at	string or null, required
import	object, required	What this request’s import did (source is contacts).
import.source	string or null, required contacts, csv	Which inline audience was imported: audience.contacts or audience.csv.
import.received	integer, required	Rows received (blank CSV lines excluded).
import.imported	integer, required	New contacts made.
import.matched_existing	integer, required	Rows whose number a contact already had: that contact was used.
import.invalid_rows	integer, required	Rows dropped because their phone number could not be read.
import.duplicate_in_file	integer, required	Rows that repeated a number earlier in the same audience.
import.skipped_rows	integer, required	Blank CSV lines skipped.
import.race_lost	integer, required	Same as Campaign.audience.import.race_lost.
import.errors	array of objects, required	Each dropped or partly read row: its line and why.
import.errors[].row	integer, required
import.errors[].message	string, required
import.warnings	array of string, required	Same as Campaign.audience.import.warnings.

Example: see Run a campaign.

ContactListAddContacts

contacts, contact_ids, or both.

field	type	description
contacts	array of objects ≤ 10,000 items	1 to 10,000 rows, as on POST /v1/lists. A number a contact already has reuses that contact; one already in the list stays once.
contacts[].phone	string, required pattern ^\+[1-9]\d{6,14}$	Same as CampaignAudience.contacts[].phone.
contacts[].name	string ≤ 200 chars	Same as CampaignAudience.contacts[].name.
contacts[].email	string ≤ 320 chars
contacts[].company	string ≤ 200 chars
contacts[].attributes	map of string to string or number or boolean	Custom fields, readable as {{contact.<key>}} in variables.
contact_ids	array of string ≤ 1,000 items; each ≤ 64 chars	Up to 1,000 contacts you already have, by ct-… id or UUID. One that is not a contact of this workspace (or was deleted) is skipped and named in import.errors.

{
  "contact_ids": [
    "ct-00000000a1"
  ]
}

ContactListMemberList

field	type	description
object	string, required always list
data	array of ContactListMember, required
has_more	boolean, required
next_cursor	string or null, required	Pass as after for the next page; null on the last.

{
  "object": "list",
  "data": [
    {
      "id": "ct-00000000a1",
      "object": "contact",
      "uuid": "00000000-0000-4000-8000-000000000012",
      "name": null,
      "phone": null,
      "email": null,
      "added_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

ContactListMember

field	type	description
id	string, required	The contact’s ct-… id.
object	string, required always contact
uuid	string, required
name	string or null, required
phone	string or null, required	E.164, or null for none.
email	string or null, required
added_at	string or null, required	When it joined the list (ISO 8601).

{
  "id": "ct-00000000a1",
  "object": "contact",
  "uuid": "00000000-0000-4000-8000-000000000012",
  "name": null,
  "phone": null,
  "email": null,
  "added_at": null
}