انتقل إلى المحتوى
المطورون

الـ Endpoints

Contacts

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

المسارات نسبية للـ base URL. كل كارت بيوضّح الصلاحية اللي الاستدعاء محتاجها وكل parameter، مع نوعه وحدوده.

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

الـ body بصيغة 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

الـ body بصيغة 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

الـ body بصيغة 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.

الـ body بصيغة 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.

الـ body بصيغة 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.

الـ body بصيغة 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.

الـ body بصيغة 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.

الـ body بصيغة 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.

الـ body بصيغة 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.

الـ body بصيغة 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.