Contacts
Contacts
Create, find and update the people you message and call. A contact is identified by its phone number, which the API never returns beyond its last four digits.
Every message and call is to a contact of the organization. You create and update contacts by phone number, find them by number or by your own reference, and keep your system in step with one reconciliation read. Reading contacts needs contacts:read; writing them needs contacts:write. Contacts do not need the messaging product.
- GET
/v1/contactsLists contacts newest first (filter by exact phone or reference), or — with updatedAfter — every contact or consent change since, oldest first - POST
/v1/contactsCreates or updates a contact by phone number - GET
/v1/contacts/{contactId}Retrieves a contact - PATCH
/v1/contacts/{contactId}Renames a contact or changes its externalReference
The contact object
{
"object": "contact",
"id": "CONTACT_ID",
"externalReference": "customer-1001",
"displayName": "Aarav Shah",
"phone": {
"last4": "3210",
"countryCode": "IN"
},
"whatsapp": {
"bsuid": null,
"username": null
},
"status": "active",
"doNotContact": false,
"createdAt": "2026-11-05T10:00:00.000Z",
"updatedAt": "2026-11-05T10:00:00.000Z"
}- The phone number never comes back beyond its last four digits (
phone.last4). To find a contact by number, ask for it (below). externalReferenceis your own id for the contact, unique in the organization.statusisactive,blockedorarchived. An archived contact is a404, like one that never existed.doNotContactmeans the contact opted out of all contact; it outranks every channel’s consent.emailandattributescan be written but are never returned.
Create or update by phone number
POST /v1/contacts creates the contact with this number (201) or updates the one that has it (200), writing only the fields you send.
curl -X POST 'https://api.trovacast.com/v1/contacts' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: contact-customer-1001' \
-H 'Content-Type: application/json' \
-d '{
"phone": "+919876543210",
"displayName": "Aarav Shah",
"externalReference": "customer-1001",
"attributes": {
"loyalty_tier": "gold"
}
}'phoneis required, in international format. It is the contact’s identity.emailis stored encrypted.attributesmerge into what the contact already carries (at most 30) — the custom fields broadcasts can target.- An
externalReferencethat belongs to a contact with a different number, or a number that carries a different reference, is409 CONFLICT: a reference never moves between numbers. - A number that was archived is revived as a fresh contact (
201): its old opt-ins are reset and it starts without the previous WhatsApp identity.
Find a contact
Ask by number — URL-encode the + — and the number is matched through the same normalization the console uses, so an exact number finds at most one contact. externalReference matches your own id exactly. Without filters the list is every live contact, newest first.
curl 'https://api.trovacast.com/v1/contacts?phone=%2B919876543210' \
-H "Authorization: Bearer $TROVACAST_API_KEY"curl 'https://api.trovacast.com/v1/contacts?externalReference=customer-1001' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Change a contact
PATCH /v1/contacts/{contactId} changes displayName and externalReference only (null clears the reference; one another contact holds is 409 CONFLICT). The number and consent cannot be changed here. A concurrent edit is retried once, then answers 409 CONFLICT.
curl -X PATCH 'https://api.trovacast.com/v1/contacts/CONTACT_ID' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: rename-customer-1001' \
-H 'Content-Type: application/json' \
-d '{
"displayName": "Aarav S."
}'Contacts without a phone number
A WhatsApp customer who hides their number behind a username reaches the business with only a business-scoped user id (whatsapp.bsuid). Where the organization creates contacts for unknown senders, such a customer becomes a contact with phone: null. Every contact has a phone number, a WhatsApp user id, or both. A contact without a number:
- can be messaged on WhatsApp — every message type except authentication templates;
- can never be called: dialling them is
422 CONTACT_PHONE_REQUIRED; - gains its number by itself if WhatsApp later shares it on one of the customer’s messages;
- is not found by
?phone=and is not created byPOST /v1/contacts, which always needs a number.
Keep your system in step
GET /v1/contacts?updatedAfter=<instant> lists every live contact whose own record or whose consent on any channel changed at or after that instant, oldest change first. Each carries two extra fields: changedAt (its place in this read) and consent — its consent on WhatsApp, email and SMS, as the consent reads return it. A STOP, an unsubscribe or a spam report changes the consent, not the contact, and still moves it here — so after an outage, this one read finds every opt-out your webhook missed.
curl 'https://api.trovacast.com/v1/contacts?updatedAfter=2026-11-05T00%3A00%3A00.000Z&limit=100' \
-H "Authorization: Bearer $TROVACAST_API_KEY"- Page with
nextCursoruntil it isnull— a page may hold fewer contacts thanlimit, even none, while it is not. - Then resume later from the last
changedAtyou saw, and deduplicate onid+changedAt. - Changes from the last 3 minutes are held back until no earlier change can still commit, so resuming never skips one.
- It cannot be combined with
phoneorexternalReference(400), and its cursor is its own. Archived and erased contacts are not listed.
Export and erase
Everything held about a contact can be exported, and a contact can be erased for good — see Data requests and erasure.