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.
- GET
/v1/contacts/{contactId}/exportExports everything held about a contact - DELETE
/v1/contacts/{contactId}Erases a contact and everything held about them - POST
/v1/organizations/{organizationId}/data-subjects/searchFinds the contacts that hold a data subject’s phone number - GET
/v1/organizations/{organizationId}/contacts/{contactId}/exportExports everything held about a contact, for its data subject - DELETE
/v1/organizations/{organizationId}/contacts/{contactId}Erases a contact and everything held about them - DELETE
/v1/organizations/{organizationId}Erases an organization the integration provisioned
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.
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.undecryptableFieldslists any value that could not be opened (reported asnull).consents— consent per channel, with source, opt-in time and the recorded evidence;attestations— the bulk-import attestations behind them.conversationsandmessages(message text included),calls(direction, status, times, duration) andfollowUps.
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.
curl -X DELETE 'https://api.trovacast.com/v1/contacts/CONTACT_ID' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: erase-customer-1001'- 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_PROGRESSbefore anything is touched — retry shortly. - Stored files — WhatsApp media and call recordings — are deleted. If storage refuses, the request answers
503 ERASURE_STORAGE_UNAVAILABLEbefore any record is touched — retry. - Cached API responses that name the contact are deleted.
- 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.
| Kept | Why | What is removed from it |
|---|---|---|
| Calls with the contact, and their charges | Call history and billing | The 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 entries | The record of what was charged | Detached from the deleted message: category and amount only. |
| Audit entries | Tamper-evident and append-only | Nothing — they hold only ids and counts, never a number, an address or text. |
| Email suppressions | An address that bounced or complained must never be mailed again | Nothing — they hold a keyed hash, not the address. |
| The erased contact’s id | So a repeat answers 204, not 404 | — |
- Idempotent. A repeat — with or without the same
Idempotency-Key— answers204. An id that never belonged to the organization is404. - 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/searchwith 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}/exportreturns the export above.DELETE /v1/organizations/{organizationId}/contacts/{contactId}erases the contact exactly as above, with the same answers.
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"
}'{
"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:
curl -X DELETE 'https://api.trovacast.com/v1/organizations/ORGANIZATION_ID' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: shop-redact-acme'{
"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}reportserasure: { status, requestedAt }. A repeatDELETEis202with the samerequestedAt; 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
| Code | Status | Meaning and what to do |
|---|---|---|
CONTACT_CALL_IN_PROGRESS | 409 | The 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_PROGRESS | 409 | A 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_UNAVAILABLE | 503 | Stored 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. |