Create a contact

Creates a contact. If a contact with the same email, the same phone (with the same country code) or the same WhatsApp user ID already exists in the organization, that contact is updated with the data you send and returned instead of creating a duplicate.

Endpoint

POST
/contacts

Body

NameTypeRequiredDescription
organization_idintegerYesOrganization to create the contact in.
first_namestringNoFirst name.
last_namestringNoLast name.
emailstringNoEmail address.
phonestringNoPhone. Send it in international format (+12025550143) or as a national number together with phone_country_code.
phone_country_codestringNoDialing code, e.g. +1. A missing + is added.
phone_country_isostringNoISO country code, e.g. US.
company_idintegerNoCompany the contact belongs to.
owned_by_user_idintegerNoOwner. Must be a member of the organization. Defaults to the API key's user.
system_typestringNolead, contact or conversation.
custom_fields_by_keyobjectNoCustom field values keyed by field key. Values are validated against the field type; unknown keys are rejected.
tagsarrayNoTags as { id, name, color } objects.
avatar_urlstringNoProfile picture URL.
channel_whatsapp_wa_idstringNoWhatsApp ID (international number, digits only).

Any other writable field from the contact object is accepted. created_by_user_id is always set to the API key's user.

Request

Response

json

Creating a contact triggers the organization's "contact created" automations.

Errors

StatusWhen
400 Bad Requestowned_by_user_id is not a member of the organization, a custom field key is unknown, or a custom field value does not match its type.
403 Forbiddenorganization_id is missing or not accessible with your key.

Report an issue with this documentation

Please log in to report issues with our documentation.