Перейти к содержимому
Разработчикам

Endpoints

Contacts

Create, find, update, tag, stage and merge the people your business talks to.

Пути указаны относительно базового URL. В каждой карточке указано, какое разрешение нужно для вызова, и перечислены все параметры с типами и ограничениями.

GET
/contacts

Search contacts, newest first.

Разрешение: contacts
Постраничный

Параметры запроса

  • qнеобязательноstring

    Free-text search across name, email, phone, WhatsApp number, notes and Instagram username. Every word must match. Up to 200 characters.

  • phoneнеобязательноstring

    Exact phone or WhatsApp number match.

  • emailнеобязательноstring

    Exact email match.

  • tagнеобязательноstring

    Contacts that carry this tag (case-insensitive).

  • stage_idнеобязательноinteger

    Contacts in this funnel stage.

  • assigned_to_user_idнеобязательноstring

    Contacts owned by this team member.

  • channelнеобязательноenum

    Contacts that came from this channel.

    Допустимые значения:instagramfacebooktiktokwhatsapptelegramemailwidgetapivoicesms

  • updated_sinceнеобязательноstring (ISO 8601 date-time with offset)

    Contacts updated at or after this time.

GET
/contacts/lookup

Find one contact by phone, email or channel username. Send at least one of phone, email or handle.

Разрешение: contacts

Параметры запроса

  • phoneнеобязательноstring

    Phone or WhatsApp number.

  • emailнеобязательноstring

    Email address.

  • handleнеобязательноstring

    Channel username, with or without "@".

  • channelнеобязательноenum

    Limit the handle search to one channel.

    Допустимые значения:instagramtiktoktelegramwhatsapp

  • Answers 404 not_found when nothing matches. When several contacts match, the oldest one is returned.
POST
/contacts

Create a contact.

Разрешение: contacts

Тело JSON

  • first_nameнеобязательноstring | null

    1–100 characters.

  • last_nameнеобязательноstring | null

    1–100 characters.

  • emailнеобязательноstring | null

    Valid email address, up to 320 characters. Stored lowercase.

  • phoneнеобязательноstring | null

    3–50 characters. E.164 (+14155550123) recommended.

  • whatsapp_phoneнеобязательноstring | null

    WhatsApp number, 3–50 characters.

  • instagram_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • tiktok_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • telegram_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • country_codeнеобязательноstring

    Two-letter ISO 3166-1 country code, e.g. "US".

  • custom_fieldsнеобязательноobject

    Custom field values keyed by custom field key (see GET /custom-fields). Merged into existing values. Unknown, archived or wrongly typed keys answer 422.

  • sourceнеобязательноstring

    Where the contact came from, up to 50 characters. Default "api".

  • tagsнеобязательноarray of strings

    Up to 100 tag names (1–80 characters each). Tags that do not exist yet are added to the workspace.

  • stage_idнеобязательноinteger

    Funnel stage to place the contact in (see GET /funnels).

  • assigned_to_user_idнеобязательноstring

    Team member who owns the contact (see GET /users).

  • Answers 201 with the contact.
POST
/contacts/upsert

Update the matching contact, or create it. Matches by phone (or whatsapp_phone), then email, then Instagram, TikTok or Telegram username.

Разрешение: contacts

Тело JSON

  • first_nameнеобязательноstring | null

    1–100 characters.

  • last_nameнеобязательноstring | null

    1–100 characters.

  • emailнеобязательноstring | null

    Valid email address, up to 320 characters. Stored lowercase.

  • phoneнеобязательноstring | null

    3–50 characters. E.164 (+14155550123) recommended.

  • whatsapp_phoneнеобязательноstring | null

    WhatsApp number, 3–50 characters.

  • instagram_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • tiktok_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • telegram_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • country_codeнеобязательноstring

    Two-letter ISO 3166-1 country code, e.g. "US".

  • custom_fieldsнеобязательноobject

    Custom field values keyed by custom field key (see GET /custom-fields). Merged into existing values. Unknown, archived or wrongly typed keys answer 422.

  • sourceнеобязательноstring

    Where the contact came from, up to 50 characters. Default "api".

  • tagsнеобязательноarray of strings

    Up to 100 tag names (1–80 characters each). Tags that do not exist yet are added to the workspace.

  • stage_idнеобязательноinteger

    Funnel stage to place the contact in (see GET /funnels).

  • assigned_to_user_idнеобязательноstring

    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.
POST
/contacts/merge

Merge a duplicate contact into another. The secondary contact's records (conversations, bookings, orders and more) move to the primary one.

Разрешение: contacts

Тело JSON

  • primary_contact_idобязательноinteger

    The contact that stays.

  • secondary_contact_idобязательноinteger

    The duplicate that is merged away. Must differ from primary_contact_id.

GET
/contacts/:id

Retrieve a contact, including tags, stage, assignee and custom fields.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

PATCH
/contacts/:id

Update contact fields. Fields you leave out keep their value; null clears a field.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

Тело JSON

  • first_nameнеобязательноstring | null

    1–100 characters.

  • last_nameнеобязательноstring | null

    1–100 characters.

  • emailнеобязательноstring | null

    Valid email address, up to 320 characters. Stored lowercase.

  • phoneнеобязательноstring | null

    3–50 characters. E.164 (+14155550123) recommended.

  • whatsapp_phoneнеобязательноstring | null

    WhatsApp number, 3–50 characters.

  • instagram_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • tiktok_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • telegram_usernameнеобязательноstring | null

    Up to 100 characters. A leading "@" is removed.

  • country_codeнеобязательноstring

    Two-letter ISO 3166-1 country code, e.g. "US".

  • custom_fieldsнеобязательноobject

    Custom field values keyed by custom field key (see GET /custom-fields). Merged into existing values. Unknown, archived or wrongly typed keys answer 422.

DELETE
/contacts/:id

Delete a contact and the data derived from it, the same way a delete in the app does.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

GET
/contacts/:id/channels

List the channel identities a contact can be reached on.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

POST
/contacts/:id/tags

Add tags to a contact. Tags that do not exist yet are added to the workspace.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

Тело JSON

  • tagsобязательноarray of strings

    1–100 tag names, 1–80 characters each.

DELETE
/contacts/:id/tags

Remove tags from a contact (case-insensitive). The tags stay in the workspace.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

Тело JSON

  • tagsобязательноarray of strings

    1–100 tag names.

PUT
/contacts/:id/stage

Move a contact to a funnel (lifecycle) stage.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

Тело JSON

  • stage_idобязательноinteger

    Target stage (see GET /funnels).

  • funnel_idнеобязательноinteger

    Optional check: the stage must belong to this funnel.

DELETE
/contacts/:id/stage

Remove the contact from its lifecycle stage.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

PUT
/contacts/:id/assignee

Assign the contact to a team member, or unassign it.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

Тело JSON

  • user_idнеобязательноstring | null

    A user from GET /users. Omit or send null to unassign.

GET
/contacts/:id/notes

List the internal notes on a contact, newest first.

Разрешение: contacts
Постраничный

Параметры пути

  • idобязательноinteger

    Contact ID.

POST
/contacts/:id/notes

Add an internal note to a contact. Customers never see notes.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

Тело JSON

  • bodyобязательноstring

    1–10,000 characters.

PUT
/contacts/:id/dnc

Turn do-not-contact on or off for a contact.

Разрешение: contacts

Параметры пути

  • idобязательноinteger

    Contact ID.

Тело JSON

  • do_not_contactобязательноboolean

    true opts the contact out of messages.

  • reasonнеобязательноstring

    Up to 200 characters.

GET
/funnels

List funnels with their stages, for use with stage_id.

Разрешение: contacts

Параметры запроса

  • flatнеобязательноstring

    "true" returns one row per stage (funnel name › stage name) instead of nested funnels.