Skip to main content
POST
Erase contacts by identifier
Deletes or anonymizes the contacts that one of your identifiers names: your own id for the person, their phone number, or their e-mail address. Use it to act on an erasure request when you do not hold our contact id. This action cannot be undone.

Request

The API key needs the delete:contacts scope, the same as Delete Contact.

How an identifier matches

  • externalId matches the externalId you stored in the contact’s metadata, and the id a connected ATS or CRM synced the contact under.
  • phoneNumber matches ignoring spaces, dashes and brackets, so +421 915-123 456 finds a contact stored as +421915123456. The country prefix is not guessed: 0915123456 does not.
  • email matches case-insensitively.
Only contacts of your API key’s company are searched, and only live ones. A contact you already deleted is on its way out with its recordings, so it is not matched again.

When more than one contact matches

Two records that share an e-mail address or an external id are not necessarily one person: a shared family mailbox, an id reused across two systems. So by default the request is refused with 409 Conflict and nothing is erased. The error message lists the matching contact ids. Check them, then either send the same request with "allowMultiple": true to erase all of them, or delete the right one with Delete Contact. One request erases at most 50 contacts. An identifier that matches more is refused with 422 Unprocessable Entity, even with allowMultiple.

Delete or anonymize

The contact is deleted exactly as Delete Contact deletes it, with every conversation it had: transcripts, analyses, documents, job assignments, field values. Afterwards GET /contacts/{id} answers 404.
In both modes the contact’s ATS and CRM links are removed, so the next sync cannot write the person’s data back.

Recordings and calls at the voice provider

Call recordings and the call records held by our voice provider are queued for deletion in the same transaction that deletes the contact, and deleted right after it. A deletion the provider does not confirm is retried automatically for several days. Nothing you need to do, and nothing lost if a provider is briefly down.

Response

Nothing matching is not an error: the answer is a 200 with an empty contactIds. That makes a retried request safe, since the second attempt finds nothing left to erase.

Error Scenarios

  • 400 Bad Request: an unknown identifierType or mode, or an empty value
  • 409 Conflict: more than one contact matches and allowMultiple is not true. Nothing was erased
  • 422 Unprocessable Entity: more than 50 contacts match. Nothing was erased
As with Delete Contact, a snapshot of the deleted contact record is kept in an internal archive for the configured retention period (30 days by default) and then removed. It is not reachable through the API.

Delete Contact

Delete one contact by its id

Contacts Resource Guide

Learn about managing contacts

Authorizations

Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

companyId
string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json
identifierType
enum<string>
required

Which identifier value is. externalId matches the contact's metadata.externalId and the id an ATS or CRM integration synced the contact under; phoneNumber matches ignoring spaces, dashes and brackets; email matches case-insensitively.

Available options:
externalId,
phoneNumber,
email
Example:

"externalId"

value
string
required

The identifier itself.

Maximum string length: 512
Example:

"CAND-12345"

mode
enum<string>
default:delete

delete removes the contact as DELETE /contacts/{id} does. anonymize removes everything the same way but leaves a record with the same id, status, source and dates and no personal data, so the id keeps resolving.

Available options:
delete,
anonymize
Example:

"delete"

allowMultiple
boolean
default:false

Erase every contact the identifier matches. Off by default: when more than one contact matches, the request is refused with 409 and erases nothing, because two records sharing an e-mail address are not necessarily one person. At most 50 contacts are erased per request.

Example:

false

Response

200 - application/json
mode
enum<string>
required

What was done to the matched contacts.

Available options:
delete,
anonymize
Example:

"delete"

identifierType
enum<string>
required

The identifier type the request matched on.

Available options:
externalId,
phoneNumber,
email
Example:

"externalId"

contactIds
string<uuid>[]
required

Ids of the contacts erased. Empty when nothing matched. With anonymize these ids still resolve, to records with no personal data.

Example: