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
| Method | Path | Description |
|---|---|---|
GET | /contacts | List contacts |
GET | /contacts/:id | Get a contact |
POST | /contacts | Create a contact |
PATCH | /contacts/:id | Update a contact |
DELETE | /contacts/:id | Delete a contact |
POST | /contacts + X-Service-Method: search | Search 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
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Organization that owns the contact. Required on create. |
first_name | string | null | First name. |
last_name | string | null | Last name. |
email | string | null | Email address (must be a valid email). |
avatar_url | string | null | Profile picture URL or storage key. |
phone_country_code | string | null | Dialing code with +, e.g. +1. Filled automatically when phone is sent in international format. |
phone_country_iso | string | null | ISO 3166 country code of the phone, e.g. US. Filled automatically when it can be detected. |
phone | string | null | National phone number. An international number such as +12025550143 is split into phone_country_code, phone_country_iso and phone. |
company_id | integer | null | Company the contact belongs to. |
created_by_user_id | integer | null | Read-only. User who created the contact (the API key's user). |
owned_by_user_id | integer | null | User who owns the contact. Defaults to the API key's user; must be a member of the organization. |
system_type | string | Classification of the record: lead, contact or conversation. |
channel_whatsapp_wa_id | string | null | WhatsApp ID (phone number in international format, digits only). |
channel_whatsapp_wa_user_id | string | null | WhatsApp Business-Scoped User ID, used when WhatsApp hides the phone number. |
channel_whatsapp_username | string | null | WhatsApp username, when WhatsApp provides one. |
channel_instagram_user_id | string | null | Instagram-scoped user ID of the contact. |
meta_psid | string | null | Facebook Messenger page-scoped ID of the contact. |
meta_facebook_user_id | string | null | Facebook user ID of the contact. |
whatsapp_blacklist | boolean | Do Not Disturb on WhatsApp: blocks every outbound WhatsApp message. Default false. |
whatsapp_blacklist_reason | string | null | Why WhatsApp DND was turned on. |
sms_blacklist | boolean | Do Not Disturb on SMS. Default false. |
sms_blacklist_reason | string | null | Why SMS DND was turned on. |
sms_opt_in_at | string (date-time) | null | When the contact opted in to SMS. |
sms_opt_in_source | string | null | Where the SMS opt-in came from. |
voice_blacklist | boolean | Do Not Disturb on voice calls. Default false. |
voice_blacklist_reason | string | null | Why voice DND was turned on. |
instagram_blacklist | boolean | Do Not Disturb on Instagram. Default false. |
instagram_blacklist_reason | string | null | Why Instagram DND was turned on. |
messenger_blacklist | boolean | Do Not Disturb on Facebook Messenger. Default false. |
messenger_blacklist_reason | string | null | Why Messenger DND was turned on. |
dnd_updated_at | string (date-time) | null | Last time any DND flag changed. Set automatically when a patch changes a *_blacklist field. |
dnd_source | string | null | Origin of the last DND change: manual, ai_assistant, automation, keyword, bulk or system. Defaults to manual for API changes. |
custom_fields_by_key | object | Custom field values keyed by the field key (see Custom fields, entity_type=contact). This is the field you write. |
custom_fields_by_name | object | Read-only. Same values keyed by the field name. Rebuilt from custom_fields_by_key. |
custom_fields_meta_data | array | Read-only. One entry per value: custom_field_id, custom_field_key, custom_field_name, custom_field_value. |
tags | array | Tags as { id, name, color } objects. Default []. |
created_at | string (date-time) | Read-only. Creation time. |
updated_at | string (date-time) | Read-only. Last update time. |
deleted_at | string (date-time) | null | Read-only. Set when the contact is deleted. |
Related
Report an issue with this documentation
Please log in to report issues with our documentation.