API reference

Customers

/contacts

A customer is the person who receives messages. Customers are subscribed to subscriptions through /links. In the Subscription business pack a customer is, for example, “Hawa Kollie”.

GET/contactsList · ?q ?phone_e164 ?external_ref POST/contactsCreateshown →GET/contacts/{contact_id}Read PATCH/contacts/{contact_id}Update · attributes replaced whole POST/contacts/{contact_id}/deactivateDeactivate · no delete

POSTCreate a customer

Requires contacts:write. A name and a way to reach them are enough. A customer needs a phone number or an email address, never neither. Whether this instance takes customers with no phone number at all is its own setting, off unless it was turned on, and not something the API tells you: where it is off, a create with no number comes back 400 — “This organisation does not allow contacts without a phone number. Add a phone number, or allow it in Settings.” Unknown keys inside attributes are refused with 400.

Body parameters

namestring · required

“Hawa Kollie”.

phone_e164string · optional · E.164

+231881872270. Spaces and dashes are removed; a bare Liberian number is read as +231. Leave it out only where the instance takes customers with no phone number: then email and external_ref are both required.

wa_phone_e164string · optional · E.164

Only when WhatsApp is on a different number. Left out, WhatsApp goes to phone_e164. It goes beside a phone number and never in place of one, so a customer with no phone number cannot have one.

emailstring · optional

Lower-cased, and two customers may share one. Beside a phone number it is an extra address; with no phone number it is the one way to reach them, and required. Used only when the instance has connected a Gmail account and switched email on.

external_refstring · optional · max 200

Your own id for the customer. It is what q finds, what ?external_ref= looks up exactly, and what makes a re-sync an update. A customer with no phone number must have one: it is the only thing a later import or update can find them by.

channel_prefsms | whatsapp | email · default sms

email needs an email address on the contact, and is refused with 400 without one. So is taking the address away from a contact who prefers email: change the preference first, or in the same call. A customer with no phone number can only be reached by email, so it is set to email when you send none, and sms or whatsapp is refused with 400.

languagestring · default en

Picks the wording variant.

roleaudience | staff · default audience

Set once. Staff receive copies, not notices.

attributesobject · optionalVaries by pack

Generated from the Subscription business pack's contact_schema. PATCH replaces the whole object; it does not merge.

KeyLabelKindAllowed valuesRequired

companyCompanytext—No

timezoneTime zonetext—No

job_titleJob titletext—No

Returns

201 with the customer. 400 when the body would leave somebody nobody can reach, in a sentence naming the rule: a number or an address, a reference where there is no number, no WhatsApp number in place of a phone number, email as the preferred channel. 409 conflict if the number is already on file in this instance: find it with ?phone_e164 and update that record instead. 409 if the reference is already on file — “That reference already belongs to someone else on file. Find them with ?external_ref= and update that record instead.”

Response body

One customer: the same fields in every pack. Press Response on the sample to see one whole.

FieldTypeDescription

iduuid

tenant_iduuidThe instance.

external_refstring | nullYour own id, as you sent it. It is the only exact key a customer with no phone number has.

namestring

roleaudience | staffSet when the contact is made and never changed.

phone_e164string | nullNormalised to E.164, whatever shape it arrived in. null where the instance takes customers with no phone number: then the email is the address and external_ref is the key.

wa_phone_e164string | nullnull means WhatsApp goes to phone_e164, where there is one. It goes beside a phone number and never in place of one, so a customer with no phone number has no WhatsApp number either.

emailstring | nullLower-cased. Not unique: two people may share one. It is the one way to reach a customer with no phone number.

channel_prefsms | whatsapp | emailUsed where a send follows preferences. email means the email goes in place of the phone message, unless the instance keeps the phone for that kind of notice. With no phone number there is nothing else, so a customer without one is always email.

wa_reachableboolean | nullLearned, not set: null is untried, false is a send that came back unreachable, true is one that landed.

sms_reachableboolean | nullThe same, for SMS.

last_inbound_atdatetime | nullWhen this customer last wrote in. Anchors WhatsApp's 24-hour reply window.

wa_opt_out_atdatetime | nullWhen this customer wrote STOP on WhatsApp. WhatsApp is skipped from then on; SMS is not. START clears it.

languagestring

attributesobjectShaped by the Subscription business pack's contact_schema.Varies by pack

statusactive | inactive | blocked | opt_outOnly active contacts are ever messaged.

created_atdatetime

updated_atdatetime

On failure the body is { error, code } instead.

Previous← Authentication, keys and scopes NextEvent types →