Contacts

Sync your customers with Nevox using your own ID.

A contact is a person the agent talks to. You identify each contact by your ID, the external_id. That way you don't need to store Nevox IDs in your database.

Coming soon, Nevox will also merge the same contact coming from different channels when the phone number or email matches.

Create or update (upsert)

PUT /v1/contacts/{external_id} · scope contacts:write

bash

curl -X PUT https://api.nevox.ai/v1/contacts/patient_1042 \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mary Smith",
    "email": "mary@example.com",
    "phone": "+14125550123",
    "language": "en-US",
    "tags": ["family-plan"],
    "metadata": { "city": "Orlando" }
  }'

json

{
  "id": "ctc_4hq81",
  "external_id": "patient_1042",
  "name": "Mary Smith",
  "email": "mary@example.com",
  "phone": "+14125550123",
  "language": "en-US",
  "tags": ["family-plan"],
  "metadata": { "city": "Orlando" },
  "channels": ["api", "whatsapp"],
  "first_seen_at": "2026-09-14T18:02:00Z",
  "last_seen_at": "2026-11-03T14:30:00Z",
  "created_at": "2026-09-14T18:02:00Z",
  "updated_at": "2026-11-03T14:30:00Z"
}

Field	Type	Notes
`name`	string
`email`	string
`phone`	string	International E.164 format (`+5511...`, `+1412...`)
`language`	string	`pt-BR`, `en-US` or `es`
`tags`	string[]	Up to 20
`metadata`	object	Up to 50 keys; string, number or boolean values

The agent sees name, language and tags. metadata is available to actions and to analytics, but is not shown to the agent. Don't put sensitive information (diagnoses, ID documents, card data) in any field.

Read

Endpoint	Scope
`GET /v1/contacts/{external_id}`	`contacts:read`
`GET /v1/contacts?tag=&email=&phone=&updated_after=`	`contacts:read`
`GET /v1/contacts/{external_id}/timeline`	`analytics:read`. See analytics.

Delete (right to be forgotten)

DELETE /v1/contacts/{external_id} · scope contacts:write

Deletes the contact and the conversations and messages linked to it, immediately. Deletion is permanent. Use it to handle data deletion requests (LGPD, CCPA).

json

{ "id": "ctc_4hq81", "deleted": true }