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_refPOST/contactsCreateGET/contacts/{contact_id}Readshown →PATCH/contacts/{contact_id}Update · attributes replaced wholePOST/contacts/{contact_id}/deactivateDeactivate · no delete
GETRead a person
Requires contacts:read. Returns the person as stored, whatever its status.
Path parameters
contact_iduuid · required
The person id.
Returns
200 with the person. 404 not_found if the id is not in this instance.
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.
marketing_consent_atdatetime | nullWhen this person agreed to promotions. A marketing wording reaches only a person who has, and has not stopped since.
marketing_consent_sourcestaff | import | api | reply | nullHow Raven was told: by hand, in a file, by your system, or by the person writing START PROMOTIONS.
marketing_opt_out_atdatetime | nullWhen they stopped promotions: the Stop promotions button, STOP PROMOTIONS, or WhatsApp's own marketing switch.
languagestring
attributesobjectShaped by the Political party pack's contact_schema.Varies by pack
statusactive | inactive | blocked | opt_outOnly active contacts are ever messaged.
managed_bystring | nullThe linked Utilitay product that keeps this person, with managed_instance and managed_ref; null for one of the organisation's own. A managed contact's name, phone number and email are changed in that product: an update of them here is refused with 400.
managed_instancestring | null
managed_refstring | null
created_atdatetime
updated_atdatetime
On failure the body is { error, code } instead.