Trovacast

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.

The contact object

A contact (json)
{
  "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).
  • externalReference is your own id for the contact, unique in the organization.
  • status is active, blocked or archived. An archived contact is a 404, like one that never existed.
  • doNotContact means the contact opted out of all contact; it outranks every channel’s consent.
  • email and attributes can 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.

Create or update a contact
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"
  }
}'
  • phone is required, in international format. It is the contact’s identity.
  • email is stored encrypted. attributes merge into what the contact already carries (at most 30) — the custom fields broadcasts can target.
  • An externalReference that belongs to a contact with a different number, or a number that carries a different reference, is 409 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.

Find a contact by phone number
curl 'https://api.trovacast.com/v1/contacts?phone=%2B919876543210' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
Find a contact by your reference
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.

Rename a contact
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 by POST /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.

Contacts changed since a moment
curl 'https://api.trovacast.com/v1/contacts?updatedAfter=2026-11-05T00%3A00%3A00.000Z&limit=100' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
  • Page with nextCursor until it is null — a page may hold fewer contacts than limit, even none, while it is not.
  • Then resume later from the last changedAt you saw, and deduplicate on id + 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 phone or externalReference (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.