Skip to navigation

Delete caller data

Erases what the platform keeps about a phone number for your organization (GDPR art. 17): calls, transcripts, call events and outbound contacts, and returns how many records were erased. It cannot be undone, so the number must be sent twice. It is refused while a call with that number is in progress. An objection is never erased: the number stays on the do-not-call list, so the objection keeps being honoured. If the erasure stops halfway, repeat the same request with the same Idempotency-Key: it completes it. The request is recorded in the register. Required scope: caller_requests:manage. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Requires an Idempotency-Key header. Retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the key is released and a retry with the same key runs the operation again; with no response at all, a retry with the same key returns the first outcome or runs the operation again. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:
Idempotency-KeystringRequiredformat: "^[A-Za-z0-9_-]{16,64}$"

A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.

Request

This endpoint expects an object.
phone_numberstringRequiredformat: "^\+[1-9][0-9]{6,14}$"

The phone number of the person, in international format (E.164), for example +393331234567. It travels only in the request body.

confirm_phone_numberstringRequired1-32 characters

The same phone number again. If it differs from phone_number nothing is erased (422 phone_confirmation_mismatch).

received_atdatetimeOptional

When you received the person’s request (ISO 8601). It starts the one-month deadline of GDPR art. 12(3). Default: now. Not earlier than 365 days ago and not in the future.

referencestringOptionalformat: "^[A-Za-z0-9._:-]{1,64}$"

Your own reference for the request, for example the case number: 1 to 64 letters, digits, dots, underscores, colons or hyphens. It must not be personal data.

Response

Successful response.
object"caller_erasure"

Always caller_erasure.

idstringformat: "uuid"
The id of the request in the register. With a test key it does not exist.
statusenum

completed: the data was erased. simulated: test key, nothing was erased.

Allowed values:
recordsobject

What was erased (with a test key: what would be erased).

objection_activeboolean

The erasure never removes an objection: the do-not-call list is kept so that the objection can be honoured.

received_atdatetime

When you received the request (received_at of the body, or now), ISO 8601 UTC.

due_atdatetime

The one-month deadline of the request, ISO 8601 UTC.

completed_atdatetime or null

When the erasure was completed, ISO 8601 UTC; null with a test key.

lateboolean

True if the erasure was completed after the one-month deadline.

simulatedboolean

true with a test key: nothing was erased and nothing was recorded in the register.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error