Contacts

A contact is a person your organization talks to: a lead, a customer or someone who wrote to one of your channels (WhatsApp, Instagram, Messenger, SMS, webchat). Use this resource to sync people from another system, look them up by phone or email, and keep their custom fields, tags and Do Not Disturb flags up to date.

Endpoints

MethodPathDescription
GET/contactsList contacts
GET/contacts/:idGet a contact
POST/contactsCreate a contact
PATCH/contacts/:idUpdate a contact
DELETE/contacts/:idDelete a contact
POST/contacts + X-Service-Method: searchSearch contacts

Reads are limited to your API key's organization. Pass organization_id as a filter to work with one organization.

The contact object

json

Fields

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerOrganization that owns the contact. Required on create.
first_namestring | nullFirst name.
last_namestring | nullLast name.
emailstring | nullEmail address (must be a valid email).
avatar_urlstring | nullProfile picture URL or storage key.
phone_country_codestring | nullDialing code with +, e.g. +1. Filled automatically when phone is sent in international format.
phone_country_isostring | nullISO 3166 country code of the phone, e.g. US. Filled automatically when it can be detected.
phonestring | nullNational phone number. An international number such as +12025550143 is split into phone_country_code, phone_country_iso and phone.
company_idinteger | nullCompany the contact belongs to.
created_by_user_idinteger | nullRead-only. User who created the contact (the API key's user).
owned_by_user_idinteger | nullUser who owns the contact. Defaults to the API key's user; must be a member of the organization.
system_typestringClassification of the record: lead, contact or conversation.
channel_whatsapp_wa_idstring | nullWhatsApp ID (phone number in international format, digits only).
channel_whatsapp_wa_user_idstring | nullWhatsApp Business-Scoped User ID, used when WhatsApp hides the phone number.
channel_whatsapp_usernamestring | nullWhatsApp username, when WhatsApp provides one.
channel_instagram_user_idstring | nullInstagram-scoped user ID of the contact.
meta_psidstring | nullFacebook Messenger page-scoped ID of the contact.
meta_facebook_user_idstring | nullFacebook user ID of the contact.
whatsapp_blacklistbooleanDo Not Disturb on WhatsApp: blocks every outbound WhatsApp message. Default false.
whatsapp_blacklist_reasonstring | nullWhy WhatsApp DND was turned on.
sms_blacklistbooleanDo Not Disturb on SMS. Default false.
sms_blacklist_reasonstring | nullWhy SMS DND was turned on.
sms_opt_in_atstring (date-time) | nullWhen the contact opted in to SMS.
sms_opt_in_sourcestring | nullWhere the SMS opt-in came from.
voice_blacklistbooleanDo Not Disturb on voice calls. Default false.
voice_blacklist_reasonstring | nullWhy voice DND was turned on.
instagram_blacklistbooleanDo Not Disturb on Instagram. Default false.
instagram_blacklist_reasonstring | nullWhy Instagram DND was turned on.
messenger_blacklistbooleanDo Not Disturb on Facebook Messenger. Default false.
messenger_blacklist_reasonstring | nullWhy Messenger DND was turned on.
dnd_updated_atstring (date-time) | nullLast time any DND flag changed. Set automatically when a patch changes a *_blacklist field.
dnd_sourcestring | nullOrigin of the last DND change: manual, ai_assistant, automation, keyword, bulk or system. Defaults to manual for API changes.
custom_fields_by_keyobjectCustom field values keyed by the field key (see Custom fields, entity_type=contact). This is the field you write.
custom_fields_by_nameobjectRead-only. Same values keyed by the field name. Rebuilt from custom_fields_by_key.
custom_fields_meta_dataarrayRead-only. One entry per value: custom_field_id, custom_field_key, custom_field_name, custom_field_value.
tagsarrayTags as { id, name, color } objects. Default [].
created_atstring (date-time)Read-only. Creation time.
updated_atstring (date-time)Read-only. Last update time.
deleted_atstring (date-time) | nullRead-only. Set when the contact is deleted.

Related

Report an issue with this documentation

Please log in to report issues with our documentation.