Endpoints
Contacts
Create, find, update, tag, stage and merge the people your business talks to.
Paths are relative to the base URL. Each card lists the permission the call needs and every parameter, with its type and limits.
/contactsSearch contacts, newest first.
Query parameters
- qoptionalstring
Free-text search across name, email, phone, WhatsApp number, notes and Instagram username. Every word must match. Up to 200 characters.
- phoneoptionalstring
Exact phone or WhatsApp number match.
- emailoptionalstring
Exact email match.
- tagoptionalstring
Contacts that carry this tag (case-insensitive).
- stage_idoptionalinteger
Contacts in this funnel stage.
- assigned_to_user_idoptionalstring
Contacts owned by this team member.
- channeloptionalenum
Contacts that came from this channel.
Allowed values:
instagramfacebooktiktokwhatsapptelegramemailwidgetapivoicesms - updated_sinceoptionalstring (ISO 8601 date-time with offset)
Contacts updated at or after this time.
/contacts/lookupFind one contact by phone, email or channel username. Send at least one of phone, email or handle.
Query parameters
- phoneoptionalstring
Phone or WhatsApp number.
- emailoptionalstring
Email address.
- handleoptionalstring
Channel username, with or without "@".
- channeloptionalenum
Limit the handle search to one channel.
Allowed values:
instagramtiktoktelegramwhatsapp
- Answers 404 not_found when nothing matches. When several contacts match, the oldest one is returned.
/contactsCreate a contact.
JSON body
- first_nameoptionalstring | null
1–100 characters.
- last_nameoptionalstring | null
1–100 characters.
- emailoptionalstring | null
Valid email address, up to 320 characters. Stored lowercase.
- phoneoptionalstring | null
3–50 characters. E.164 (+14155550123) recommended.
- whatsapp_phoneoptionalstring | null
WhatsApp number, 3–50 characters.
- instagram_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- tiktok_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- telegram_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- country_codeoptionalstring
Two-letter ISO 3166-1 country code, e.g. "US".
- custom_fieldsoptionalobject
Custom field values keyed by custom field key (see GET /custom-fields). Merged into existing values. Unknown, archived or wrongly typed keys answer 422.
- sourceoptionalstring
Where the contact came from, up to 50 characters. Default "api".
- tagsoptionalarray of strings
Up to 100 tag names (1–80 characters each). Tags that do not exist yet are added to the workspace.
- stage_idoptionalinteger
Funnel stage to place the contact in (see GET /funnels).
- assigned_to_user_idoptionalstring
Team member who owns the contact (see GET /users).
- Answers 201 with the contact.
/contacts/upsertUpdate the matching contact, or create it. Matches by phone (or whatsapp_phone), then email, then Instagram, TikTok or Telegram username.
JSON body
- first_nameoptionalstring | null
1–100 characters.
- last_nameoptionalstring | null
1–100 characters.
- emailoptionalstring | null
Valid email address, up to 320 characters. Stored lowercase.
- phoneoptionalstring | null
3–50 characters. E.164 (+14155550123) recommended.
- whatsapp_phoneoptionalstring | null
WhatsApp number, 3–50 characters.
- instagram_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- tiktok_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- telegram_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- country_codeoptionalstring
Two-letter ISO 3166-1 country code, e.g. "US".
- custom_fieldsoptionalobject
Custom field values keyed by custom field key (see GET /custom-fields). Merged into existing values. Unknown, archived or wrongly typed keys answer 422.
- sourceoptionalstring
Where the contact came from, up to 50 characters. Default "api".
- tagsoptionalarray of strings
Up to 100 tag names (1–80 characters each). Tags that do not exist yet are added to the workspace.
- stage_idoptionalinteger
Funnel stage to place the contact in (see GET /funnels).
- assigned_to_user_idoptionalstring
Team member who owns the contact (see GET /users).
- Send at least a phone, email or channel username to match on (422 otherwise).
- Answers { object: "contact_upsert", created, contact }: 201 when created, 200 when updated.
/contacts/mergeMerge a duplicate contact into another. The secondary contact's records (conversations, bookings, orders and more) move to the primary one.
JSON body
- primary_contact_idrequiredinteger
The contact that stays.
- secondary_contact_idrequiredinteger
The duplicate that is merged away. Must differ from primary_contact_id.
/contacts/:idRetrieve a contact, including tags, stage, assignee and custom fields.
Path parameters
- idrequiredinteger
Contact ID.
/contacts/:idUpdate contact fields. Fields you leave out keep their value; null clears a field.
Path parameters
- idrequiredinteger
Contact ID.
JSON body
- first_nameoptionalstring | null
1–100 characters.
- last_nameoptionalstring | null
1–100 characters.
- emailoptionalstring | null
Valid email address, up to 320 characters. Stored lowercase.
- phoneoptionalstring | null
3–50 characters. E.164 (+14155550123) recommended.
- whatsapp_phoneoptionalstring | null
WhatsApp number, 3–50 characters.
- instagram_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- tiktok_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- telegram_usernameoptionalstring | null
Up to 100 characters. A leading "@" is removed.
- country_codeoptionalstring
Two-letter ISO 3166-1 country code, e.g. "US".
- custom_fieldsoptionalobject
Custom field values keyed by custom field key (see GET /custom-fields). Merged into existing values. Unknown, archived or wrongly typed keys answer 422.
/contacts/:idDelete a contact and the data derived from it, the same way a delete in the app does.
Path parameters
- idrequiredinteger
Contact ID.
/contacts/:id/channelsList the channel identities a contact can be reached on.
Path parameters
- idrequiredinteger
Contact ID.
/contacts/:id/tagsAdd tags to a contact. Tags that do not exist yet are added to the workspace.
Path parameters
- idrequiredinteger
Contact ID.
JSON body
- tagsrequiredarray of strings
1–100 tag names, 1–80 characters each.
/contacts/:id/tagsRemove tags from a contact (case-insensitive). The tags stay in the workspace.
Path parameters
- idrequiredinteger
Contact ID.
JSON body
- tagsrequiredarray of strings
1–100 tag names.
/contacts/:id/stageMove a contact to a funnel (lifecycle) stage.
Path parameters
- idrequiredinteger
Contact ID.
JSON body
- stage_idrequiredinteger
Target stage (see GET /funnels).
- funnel_idoptionalinteger
Optional check: the stage must belong to this funnel.
/contacts/:id/stageRemove the contact from its lifecycle stage.
Path parameters
- idrequiredinteger
Contact ID.
/contacts/:id/assigneeAssign the contact to a team member, or unassign it.
Path parameters
- idrequiredinteger
Contact ID.
JSON body
- user_idoptionalstring | null
A user from GET /users. Omit or send null to unassign.
/contacts/:id/notesList the internal notes on a contact, newest first.
Path parameters
- idrequiredinteger
Contact ID.
/contacts/:id/notesAdd an internal note to a contact. Customers never see notes.
Path parameters
- idrequiredinteger
Contact ID.
JSON body
- bodyrequiredstring
1–10,000 characters.
/contacts/:id/dncTurn do-not-contact on or off for a contact.
Path parameters
- idrequiredinteger
Contact ID.
JSON body
- do_not_contactrequiredboolean
true opts the contact out of messages.
- reasonoptionalstring
Up to 200 characters.
/funnelsList funnels with their stages, for use with stage_id.
Query parameters
- flatoptionalstring
"true" returns one row per stage (funnel name › stage name) instead of nested funnels.