Trovacast

Contacts

Data requests and erasure

Answer access and erasure requests — GDPR, India’s DPDP Act, Shopify’s compliance webhooks — by exporting or erasing a contact, or erasing a whole organization.

Three requests answer a data subject: export everything held about a contact, erase a contact for good, and — for an integration — erase an organization it provisioned. Contact requests complete at once; an organization’s erasure completes within minutes.

Export a contact

GET /v1/contacts/{contactId}/export returns one JSON document (object: "contact_export"). It is the only endpoint that returns a full phone number — the subject’s own data, returned because they asked for it — so it has its own scope, contacts:export, which contacts:read does not imply. Every export is audited.

Export a contact
curl 'https://api.trovacast.com/v1/contacts/CONTACT_ID/export' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
  • contact — the standard contact, masked as on every other read.
  • personalData — what the standard contact masks or omits, in full: the phone number, alternate phone, email, notes, profile and custom fields, tags, lifecycle stage and the contact’s calling consent with its evidence. undecryptableFields lists any value that could not be opened (reported as null).
  • consents — consent per channel, with source, opt-in time and the recorded evidence; attestations — the bulk-import attestations behind them.
  • conversations and messages (message text included), calls (direction, status, times, duration) and followUps.

Consent history (who changed what, when) lives in the audit log and is not part of the export. An erased or unknown contact is 404. Treat the export like the personal data it is: it is served with Cache-Control: no-store.

Erase a contact

DELETE /v1/contacts/{contactId} (contacts:write) permanently deletes the contact and everything about them, and answers 204.

Erase a contact
curl -X DELETE 'https://api.trovacast.com/v1/contacts/CONTACT_ID' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: erase-customer-1001'
  1. Stored provider payloads that mention them (their number, address, WhatsApp user id or message ids) are replaced with a placeholder, and a failed one awaiting retry is withdrawn so it can never write their data back. If one is being applied at that very moment, the request answers 409 CONTACT_EVENT_IN_PROGRESS before anything is touched — retry shortly.
  2. Stored files — WhatsApp media and call recordings — are deleted. If storage refuses, the request answers 503 ERASURE_STORAGE_UNAVAILABLE before any record is touched — retry.
  3. Cached API responses that name the contact are deleted.
  4. The records, in one transaction: the contact (with its encrypted number, email and notes), its consents, conversations, messages, attachments, follow-ups, assignments, campaign targets, sequence enrollments, broadcast recipients, and the webhook events about them with their deliveries.
KeptWhyWhat is removed from it
Calls with the contact, and their chargesCall history and billingThe link to the contact, transcripts, addresses, recording consent evidence, notes and call metadata; recordings are erased and the call events deleted.
Message charges and ledger entriesThe record of what was chargedDetached from the deleted message: category and amount only.
Audit entriesTamper-evident and append-onlyNothing — they hold only ids and counts, never a number, an address or text.
Email suppressionsAn address that bounced or complained must never be mailed againNothing — they hold a keyed hash, not the address.
The erased contact’s idSo a repeat answers 204, not 404—
  • Idempotent. A repeat — with or without the same Idempotency-Key — answers 204. An id that never belonged to the organization is 404.
  • A contact on a live call is 409 CONTACT_CALL_IN_PROGRESS: retry once the call ends.
  • Not covered: copies outside Trovacast — WhatsApp’s own message logs, a carrier’s copy of a recording, and anything your webhook endpoint already received.
  • A new message from the same person afterwards creates a new contact: they contacted the business again.

When the organization is suspended

A suspended organization’s own keys answer 401 — including the ones a data request needs — while the deadline keeps running (Shopify allows 30 days). So an integration answers its customers’ data requests in the organizations it provisioned with its own key and the organizations:data-subjects scope, whatever the organization’s status:

  • POST /v1/organizations/{organizationId}/data-subjects/search with the person’s number finds the contact that holds it — zero or one — including a contact deleted in the console. It is a POST so the number stays out of URLs and access logs; it writes nothing.
  • GET /v1/organizations/{organizationId}/contacts/{contactId}/export returns the export above.
  • DELETE /v1/organizations/{organizationId}/contacts/{contactId} erases the contact exactly as above, with the same answers.
Find a data subject’s contact
curl -X POST 'https://api.trovacast.com/v1/organizations/ORGANIZATION_ID/data-subjects/search' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "phone": "+919876543210"
}'
200 OK (json)
{
  "object": "list",
  "data": [
    {
      "object": "data_subject_contact",
      "id": "CONTACT_ID"
    }
  ]
}

Erase an organization

DELETE /v1/organizations/{organizationId} (integration keys, organizations:erase) erases an organization the integration provisioned — for Shopify’s shop/redact, for example. In one step it records the request, closes the organization and revokes every API key of it, then answers 202:

Erase an organization
curl -X DELETE 'https://api.trovacast.com/v1/organizations/ORGANIZATION_ID' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: shop-redact-acme'
202 Accepted (json)
{
  "object": "organization_erasure",
  "organizationId": "ORGANIZATION_ID",
  "status": "erasing",
  "requestedAt": "2026-11-05T10:00:00.000Z"
}
  • The work then runs in the background, step by step, and resumes where it stopped after a failure: WhatsApp is disconnected; stored credentials, webhook endpoints and their secrets are deleted; media and recordings are deleted; then the data, and finally the organization itself.
  • While it runs, GET /v1/organizations/{organizationId} reports erasure: { status, requestedAt }. A repeat DELETE is 202 with the same requestedAt; one after a failed run starts it again.
  • Once it completes the organization no longer exists, so any request naming it is 404 — treat that as done.
  • Audit entries are kept (without the organization), so the audit trail stays verifiable.

Errors

CodeStatusMeaning and what to do
CONTACT_CALL_IN_PROGRESS409The contact is on a live call, so they cannot be erased yet.What to do: Retry the erasure once the call has ended (call.completed), with the same Idempotency-Key.
CONTACT_EVENT_IN_PROGRESS409A message or status about the contact is being applied right now, so the contact was not erased (nothing was touched).What to do: Retry shortly — usually seconds — with the same Idempotency-Key.
ERASURE_STORAGE_UNAVAILABLE503Stored media or a call recording could not be deleted. The erasure stopped before any record was touched; nothing was lost.What to do: Retry with backoff and the same Idempotency-Key: an erasure runs again. If it persists, contact us with the requestId.