Contacts

A contact is a person in your workspace, identified by your own externalRef. Contacts carry a phone number, preferences, opt-out state, and arbitrary attributes.

The contact object:

{
  "id": "con_…",
  "externalRef": "your-record-id",
  "phone": "+919812345678",
  "dnd": false,
  "optOut": false,
  "preferredLanguage": "hi",
  "lastContactAt": "2026-08-20T12:00:00Z",
  "attributes": { "plan": "gold" }
}

dnd reflects the platform do-not-call registry and lastContactAt are read-only (set by the system); everything else you control.

---

List contacts

GET /v1/contacts  ·  scope contacts:read  ·  query limit (1–200, default 50)

{ "data": [ { "id": "con_…", "externalRef": "…", "phone": "+91…", … } ] }

Create or update (upsert)

POST /v1/contacts  ·  scope contacts:write

Upserts by externalRef within your workspace: if a contact with that ref exists it’s updated (200), otherwise it’s created (201).

Body

Field	Type	Required	Default / constraints
externalRef	string	yes	your id, 1–120 chars (immutable identity)
phone	string	yes	8–20 chars
preferredLanguage	enum	no	en or hi, default en
timezone	string	no	default Asia/Kolkata
attributes	object	no	arbitrary key/values, default {}
optOut	boolean	no	default false

Response

201 (created) or 200 (updated): { "data": contact }.

Update a contact

PUT /v1/contacts/:id  ·  scope contacts:write

Same fields as upsert except externalRef (identity can’t change). Response 200: { "data": contact }. Unknown id → 404 contact not found.

Delete a contact

DELETE /v1/contacts/:id  ·  scope contacts:write → { "data": { "id": "con_…", "deleted": true } }.

• 409 contact has call history - cannot delete - a contact with calls can’t be hard-deleted. Use erase instead.
• 404 contact not found

Erase a contact (DPDP)

POST /v1/contacts/:id/erase  ·  scope contacts:write  ·  no body

Honors a data-subject erasure request: it wipes the contact’s personal data - identity, transcripts, and recordings - while keeping non-personal compliance proof. Unlike delete, erase works even when the contact has call history, and it’s idempotent.

Response 200: { "data": <erasure result> }. Unknown id → 404.

Next: Campaigns →