Create objection
Records that a person objects to being called (GDPR art. 21) and returns the objection: the number joins the do-not-call list of the organization and is never called again, by any key or campaign. Recording an objection that is already active changes nothing and says so in already_active. 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
Headers
API version for this request; defaults to the version the key is pinned to.
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
The phone number of the person, in international format (E.164), for example +393331234567. It travels only in the request body.
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.
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
Always caller_objection.
When the objection was recorded, ISO 8601 UTC; null after a withdrawal.
The requested state already held. Recording: the objection was already active. Withdrawing: there was nothing to withdraw.
true with a test key: nothing changed and nothing was recorded in the register.