API v3
POST /verifications
Text a one-time code to a mobile number.
Sends a 6-digit code by SMS in your account's registered company name (the legal name we verified when the account went active). 403 account_not_active until the account is active. The price for the number's country (GET /verify/prices) is taken from your prepaid balance before the code is sent, once per Idempotency-Key; a code that is not sent is refunded. 402 insufficient_balance when the balance does not cover it. A code lives 10 minutes and allows 5 checks. Up to 5 codes a second per key and per account, and 5 an hour to one number from one account. Codes are refused for countries we do not serve, and paused for a short while when traffic looks like SMS pumping. 423 account_locked when the account is locked pending a Trust & Safety review.
Addresshttps://api.voicepro.plus/v3/verifications
Key permissionverify:write
Idempotency-KeyRequired. A retry with the same key and body replays the first answer, so it never acts twice.
ChargesPaid from your account balance before it runs; a short balance is 402 and nothing runs.
Fields
| Name | In | Type | |
|---|---|---|---|
| Idempotency-Key * | header | string | Required on every POST. 8-128 characters: letters, digits, dot, colon, hyphen or underscore. The first response is stored for 24 hours and replayed for any retry with the same key and the same body. Two rules, set per operation by x-charged. Charged or partner-side operations (x-charged true: dips, dip batches, orders, SMS, porting) never re-run while a first attempt is unfinished: a retry answers 409 idempotency_key_in_use (outcome pending) until the first outcome is stored, and the key is also given to the partner as its own reference, so one key never causes more than one order, charge or message, even across failures. A charged operation that fails part-way stores that failure as the key's answer; only a refusal before anything ran (400, 401, 402, 403, 404, 429) frees the key for a retry. Operations with no outside effect (x-charged false) hold their key for at most 2 minutes; after that a retry runs fresh. Missing: 400 missing_parameter (param Idempotency-Key). Malformed: 400 invalid_parameter. Same key, different body: 409 idempotency_key_reused. First request still running: 409 idempotency_key_in_use. |
| to * | body | string | The mobile number to text the code to, in international format with a leading +. |
| channel | body | sms | How the code is sent. Only sms today. |
| currency | body | string | The balance to pay from (any currency we charge in). Defaults to your account's currency. |
* required
Example
curl -X POST "https://api.voicepro.plus/v3/verifications" \
-H "Authorization: Bearer vpkey_YOUR_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"to":"+447700900123","channel":"sms","currency":"GBP"}'Response
{
"object": "verification",
"id": "vrf_3f9a1c7e2b8d4a6f0c5e9b1d",
"to": "+447700900123",
"channel": "sms",
"status": "pending",
"checks_left": 5,
"expires_at": "2026-11-12T10:10:00Z",
"charge": {
"amount": "0.12",
"currency": "GBP"
},
"created_at": "2026-11-12T10:00:00Z",
"approved_at": null
}Errors
Every error has the same shape: { "error": { "type", "code", "message", "param", "request_id" } }.
missing_api_key401: No Authorization header, or not a Bearer key.
invalid_api_key401: The key is not recognised.
api_key_revoked401: The key was revoked in the portal.
api_key_expired401: The key passed the expiry date set on it.
missing_scope403: The key lacks the scope this endpoint needs; param names the scope.
ip_not_allowed403: The key has an IP allowlist and this request came from elsewhere.
account_not_active403: The workspace is suspended or closed.
invalid_parameter400: A query parameter or body field has a bad value; param names it.
missing_parameter400: A required parameter or field is missing; param names it.
unknown_parameter400: A parameter or field that this endpoint does not accept; param names it.
invalid_json400: The body is not valid JSON.
invalid_cursor400: The cursor is malformed, expired or from a different list.
invalid_time_range400: from or to is not an ISO 8601 date-time, or to is not after from.
range_too_long400: The time range is longer than this endpoint allows (stated in the endpoint).
route_not_found404: No such path in v3.
resource_not_found404: No object with that id on this account.
service_not_enabled404: The account does not have this service (voice trunk, IoT, numbers); param names it.
idempotency_key_reused409: This Idempotency-Key was used within 24 hours with a different request.
idempotency_key_in_use409: A request with this Idempotency-Key is still running, or its outcome at a partner is not yet known (message: outcome pending); retry shortly with the same key. If a charged request never finished, the message says so: check your balance and orders before sending it again with a new key.
state_conflict409: The object is not in a state that allows this action (for example resuming an active SIM).
insufficient_balance402: Prepaid funds or the account's order limit do not cover this charged action (a dip, an SMS or an order).
rate_limited429: Too many requests for this key or for the whole account (the message says which); wait Retry-After seconds.
upstream_unavailable503: A network partner or data service behind this endpoint is unavailable.
network_action_unavailable503: This network action is not switched on for the account yet (for example SIM suspend).
internal_error500: Our fault. Quote the request_id to support.
service_unavailable503: API v3 itself is briefly unavailable (for example a configuration problem on our side); the rest of VoicePro is unaffected. Retry later.
account_locked423: The account is locked pending a Trust & Safety review; writes, including charged actions, are refused until it is cleared. Reads still work.