Skip to navigation

Search caller data

Returns what the platform keeps about a phone number for your organization: the calls where it was the caller or the person called, the outbound contacts with it, and whether it is on the do-not-call list. Only identifiers, dates and booleans: never the content of a call. Use it to answer a person who asks whether you hold data about them, then export or erase. The search is not a request: it is not recorded in the register, so received_at and reference are accepted but not used. Required scope: caller_requests:manage. With a test key (vx_test_) it behaves exactly as with a live key and consumes nothing. This is a read that uses POST only so that its input (a phone number, a search text) travels in the body and never in the URL. It takes no Idempotency-Key, nothing is stored, and the response is never cached or repeated.

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:

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.

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_data_summary"

Always caller_data_summary.

callslist of objects
The calls of this number.
contactslist of objects
The outbound contacts with this number.
objectionobject

The do-not-call list of the organization: active is true if this number has objected to being called.

Errors

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