İçeriğe geç
Geliştiriciler

Endpoint'ler

Contacts

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

Yollar temel URL'ye göredir. Her kart, çağrının gerektirdiği izni ve her parametreyi türü ve sınırlarıyla listeler.

GET
/contacts

Search contacts, newest first.

İzin: contacts
Sayfalı

Sorgu parametreleri

  • qisteğe bağlıstring

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

  • phoneisteğe bağlıstring

    Exact phone or WhatsApp number match.

  • emailisteğe bağlıstring

    Exact email match.

  • tagisteğe bağlıstring

    Contacts that carry this tag (case-insensitive).

  • stage_idisteğe bağlıinteger

    Contacts in this funnel stage.

  • assigned_to_user_idisteğe bağlıstring

    Contacts owned by this team member.

  • channelisteğe bağlıenum

    Contacts that came from this channel.

    İzin verilen değerler:instagramfacebooktiktokwhatsapptelegramemailwidgetapivoicesms

  • updated_sinceisteğe bağlı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.

İzin: contacts

Sorgu parametreleri

  • phoneisteğe bağlıstring

    Phone or WhatsApp number.

  • emailisteğe bağlıstring

    Email address.

  • handleisteğe bağlıstring

    Channel username, with or without "@".

  • channelisteğe bağlıenum

    Limit the handle search to one channel.

    İzin verilen değerler:instagramtiktoktelegramwhatsapp

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

Create a contact.

İzin: contacts

JSON gövdesi

  • first_nameisteğe bağlıstring | null

    1–100 characters.

  • last_nameisteğe bağlıstring | null

    1–100 characters.

  • emailisteğe bağlıstring | null

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

  • phoneisteğe bağlıstring | null

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

  • whatsapp_phoneisteğe bağlıstring | null

    WhatsApp number, 3–50 characters.

  • instagram_usernameisteğe bağlıstring | null

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

  • tiktok_usernameisteğe bağlıstring | null

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

  • telegram_usernameisteğe bağlıstring | null

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

  • country_codeisteğe bağlıstring

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

  • custom_fieldsisteğe bağlı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.

  • sourceisteğe bağlıstring

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

  • tagsisteğe bağlıarray of strings

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

  • stage_idisteğe bağlıinteger

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

  • assigned_to_user_idisteğe bağlı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.

İzin: contacts

JSON gövdesi

  • first_nameisteğe bağlıstring | null

    1–100 characters.

  • last_nameisteğe bağlıstring | null

    1–100 characters.

  • emailisteğe bağlıstring | null

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

  • phoneisteğe bağlıstring | null

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

  • whatsapp_phoneisteğe bağlıstring | null

    WhatsApp number, 3–50 characters.

  • instagram_usernameisteğe bağlıstring | null

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

  • tiktok_usernameisteğe bağlıstring | null

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

  • telegram_usernameisteğe bağlıstring | null

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

  • country_codeisteğe bağlıstring

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

  • custom_fieldsisteğe bağlı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.

  • sourceisteğe bağlıstring

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

  • tagsisteğe bağlıarray of strings

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

  • stage_idisteğe bağlıinteger

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

  • assigned_to_user_idisteğe bağlı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.

İzin: contacts

JSON gövdesi

  • primary_contact_idzorunluinteger

    The contact that stays.

  • secondary_contact_idzorunluinteger

    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.

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

PATCH
/contacts/:id

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

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

JSON gövdesi

  • first_nameisteğe bağlıstring | null

    1–100 characters.

  • last_nameisteğe bağlıstring | null

    1–100 characters.

  • emailisteğe bağlıstring | null

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

  • phoneisteğe bağlıstring | null

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

  • whatsapp_phoneisteğe bağlıstring | null

    WhatsApp number, 3–50 characters.

  • instagram_usernameisteğe bağlıstring | null

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

  • tiktok_usernameisteğe bağlıstring | null

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

  • telegram_usernameisteğe bağlıstring | null

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

  • country_codeisteğe bağlıstring

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

  • custom_fieldsisteğe bağlı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.

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

GET
/contacts/:id/channels

List the channel identities a contact can be reached on.

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

POST
/contacts/:id/tags

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

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

JSON gövdesi

  • tagszorunluarray 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.

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

JSON gövdesi

  • tagszorunluarray of strings

    1–100 tag names.

PUT
/contacts/:id/stage

Move a contact to a funnel (lifecycle) stage.

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

JSON gövdesi

  • stage_idzorunluinteger

    Target stage (see GET /funnels).

  • funnel_idisteğe bağlıinteger

    Optional check: the stage must belong to this funnel.

DELETE
/contacts/:id/stage

Remove the contact from its lifecycle stage.

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

PUT
/contacts/:id/assignee

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

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

JSON gövdesi

  • user_idisteğe bağlı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.

İzin: contacts
Sayfalı

Yol parametreleri

  • idzorunluinteger

    Contact ID.

POST
/contacts/:id/notes

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

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

JSON gövdesi

  • bodyzorunlustring

    1–10,000 characters.

PUT
/contacts/:id/dnc

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

İzin: contacts

Yol parametreleri

  • idzorunluinteger

    Contact ID.

JSON gövdesi

  • do_not_contactzorunluboolean

    true opts the contact out of messages.

  • reasonisteğe bağlıstring

    Up to 200 characters.

GET
/funnels

List funnels with their stages, for use with stage_id.

İzin: contacts

Sorgu parametreleri

  • flatisteğe bağlıstring

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