API reference

People

/contacts

A person is the person who receives messages. People are linked to memberships through /links. In the Political party pack a person is, for example, “Hawa Kollie”.

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

PATCHUpdate a person

Requires contacts:write. Send only what changes — except attributes, which is replaced whole. A body that changes nothing is refused. An address or a number is taken away by sending “”; null, or leaving the key out, leaves it alone. Taking the last number away is only allowed where the instance takes people with no phone number, and leaves somebody who needs an address, a reference, no WhatsApp number and email as their channel.

Path parameters

contact_iduuid · required

The person id.

Body parameters

namestring · optional

phone_e164string · optional · E.164

Changing the number moves future messages; messages already sent keep the number they went to. “” takes the number away, where the instance takes people with no phone number; null, or leaving it out, changes nothing.

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 person with no phone number cannot have one. “” takes it away.

emailstring · optional

Lower-cased, and two people 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. “” takes it away. Used only when the instance has connected a Gmail account and switched email on.

external_refstring · optional · max 200

Changed here, never emptied: a reference nobody can look up would find nobody. Blank leaves the one on file alone.

channel_prefsms | whatsapp | email · optional

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 person with no phone number can only be reached by email, and sms or whatsapp is refused with 400.

languagestring · optional

Picks the wording variant.

attributesobject · optionalVaries by pack

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

KeyLabelKindAllowed valuesRequired

genderGenderchoiceFemale · MaleNo

addressAddresstext—No

Returns

200 with the updated person. Status is not set here; use deactivate. The rules are the ones on create, judged against the record as it will be and refused in the same sentences. 409 if the number or the reference you are moving onto this record already belongs to someone else: find them with ?phone_e164 or ?external_ref= and update that record instead.

Response body

One person: 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 person 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 people 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 person 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 person 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 person 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 person last wrote in. Anchors WhatsApp's 24-hour reply window.

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

languagestring

attributesobjectShaped by the Political party 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 →