Skip to main content
Seven tools for working with your account’s contacts and its label catalog. All of them require the contacts:manage scope — a key without it gets an auth error naming the missing scope.
list_labels is the source of truth for label ids. Campaign audiences (preview_campaign_audience, draft_campaign) and label-based filters take numeric label ids, not title strings — resolve them here first.

​
Two ids, don’t mix them

Contact database id

The id on a contact from list_contacts / search_contacts. This is what update_contact and add_contact_labels take.

Conversation display id

The per-account number shown in the UI, used by the conversation tools. It is not a contact id — never pass one where a contact_id is expected.
add_contact_labels replaces the contact’s entire label set — it is not additive. To add one label, read the contact’s current labels first and send the union.

​
Finding contacts

​
list_contacts

List contacts in the account, 15 per page. Returns {meta:{count, current_page}, payload:[contact,...]}.

​
search_contacts

Search contacts by name, email, phone number, or identifier. Returns {meta:{count, current_page, has_more}, payload:[contact,...]}.

​
filter_contacts

Advanced filtering with structured predicates. Each predicate is shaped:
Returns {meta:{count, current_page}, payload:[contact,...]}.
query_operator (and / or) chains predicates together — it belongs on each predicate, not on the request as a whole.

​
Creating & updating

​
create_contact

Create a new contact. Provide at least one identifying field — name, email, phone_number, or identifier. Returns {payload:{contact:{...}, contact_inbox:{...}}}.

​
update_contact

Update an existing contact. Only the fields you pass are changed. Returns {payload:{contact...}}.
custom_attributes are merged on update, so you can set one key without wiping the rest. This differs from labels, which are replaced wholesale.

​
Labels

​
list_labels

List the account’s labels with their numeric ids and titles. This is what you use to resolve the ids that preview_campaign_audience and draft_campaign require. Takes no arguments. Returns {payload:[{id, title, description, color, ...}]}.

​
add_contact_labels

Set the labels on a contact. Replaces the contact’s current set (not additive). Returns {payload:[label,...]}.

​
Recipe: tag a contact without losing existing labels

1

Read the current labels

Fetch the contact via search_contacts or list_contacts and note the labels it already has.
2

Send the union

Call add_contact_labels(contact_id, labels=[...existing, "new-label"]) with the full merged list — anything you omit is dropped.

Campaign Tools

Label ids from list_labels feed campaign audiences.

Authentication & Scopes

How the contacts:manage scope is granted and enforced.