API docs

Contacts & opt-outs

Contacts are your workspace’s phone book — one row per phone number, carrying consent/DND state and variables.

Contacts

  • GET /v1/contacts — filters: phone (exact E.164), q (name search), dnd_status (unknown|clean|dnd), consent_status (unknown|consented|withdrawn) + pagination.
  • GET /v1/contacts/{id}
  • POST /v1/contacts — {phone_e164 (required, E.164), name?, metadata?}. Duplicate number → 409 contact_exists with existing_id.
  • PATCH /v1/contacts/{id} — {name?, metadata?}.

Contact object: id, phone_e164, name, email, external_id, variables, metadata, consent_status, dnd_status, created_at, updated_at.

Opt-outs

Opt-outs set a number’s DND state. The dialer enforces this authoritatively — an opted-out number is refused both at POST /v1/calls time (422 recipient_dnd) and again at dial time, even if it was opted out after queueing.

  • POST /v1/opt-outs — {phone_e164, reason?} → sets dnd_status: "dnd" (creates the contact if needed) and writes an auditable consent record.
  • DELETE /v1/opt-outs/{phone_e164} → back to "clean" (also audited).
  • GET /v1/opt-outs/{phone_e164} → {phone_e164, dnd_status, consent_status}; 404 if the number is unknown.