API reference
Parents
/contacts
A parent is the person who receives messages. Parents are linked to students through /links. In the High school pack a parent is, for example, “Hawa Kollie”.
GET/contactsList · ?q ?phone_e164 ?external_refshown →POST/contactsCreateGET/contacts/{contact_id}ReadPATCH/contacts/{contact_id}Update · attributes replaced wholePOST/contacts/{contact_id}/deactivateDeactivate · no delete
GETList parents
Requires contacts:read. Returns a bare JSON array, newest first. No envelope, no total. Two exact lookups sit beside the search: by number, and by your own reference.
Query parameters
limitinteger · default 50 · max 200
offsetinteger · default 0
qstring · optional · max 100
Matches a name, part of a number, or part of a reference — CUS-1 also finds CUS-10. It is a search, not a lookup, so it cannot be combined with external_ref.
statusactive | inactive | blocked | opt_out · optional
phone_e164string · optional
How a system finds the parent it already knows by number.
roleaudience | staff · optional
external_refstring · optional · max 200
Your own id for the parent, looked up exactly: an array of one, or an empty one. It is the only exact key a parent with no phone number has. Combines with status, role and phone_e164. Refused with 400 alongside q: search, or look up.
Returns
200 with an array of parents. An empty array when nothing matches.
Response body
A bare JSON array. Each item is one parent: 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 parent 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 parents 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 parent 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 parent 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 parent 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 parent last wrote in. Anchors WhatsApp's 24-hour reply window.
wa_opt_out_atdatetime | nullWhen this parent wrote STOP on WhatsApp. WhatsApp is skipped from then on; SMS is not. START clears it.
languagestring
attributesobjectShaped by the High school 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.