Phone Verification (verify/send + verify/check)
Verify a customer's phone number with a real enterable code, by SMS or a spoken phone call - request/response shapes, billing (SMS retail vs Voice flat rate), error handling.
Phone Verification (verify/send + verify/check)
Verify one of your own customers' phone numbers with a real, enterable code — for confirming a customer really owns the number they gave you at signup, checkout, or booking. Delivers by SMS or by a real spoken phone call.
POST /api/v1/verify/send
| Field | Type | Required | Description |
|---|---|---|---|
| to | string | Yes | Customer's phone in international format e.g. +2348011234567 |
| channel | string | No | sms (default) or voice — a real call that reads the code aloud, digit by digit |
| from | string | No | Sender ID for SMS (max 11 characters). Defaults to your business name. Not used for voice. |
| voice | string | No | Voice channel only — which voice reads the code. Defaults to a US English voice. |
Example request (SMS)
curl -X POST https://app.6xcom.com/api/v1/verify/send \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"to":"+2348011234567"}'Example request (Voice)
curl -X POST https://app.6xcom.com/api/v1/verify/send \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"to":"+2348011234567","channel":"voice"}'Voice calls need at least one active phone extension on your account (the same requirement as any outbound call) — if you don't have one yet, contact support.
Response
{
"success": true,
"verification_id": 4821,
"status": "pending",
"expires_at": "2026-09-02T13:20:00+00:00"
}POST /api/v1/verify/check
Submit the code your customer typed back. A code expires after 10 minutes and allows up to 5 incorrect attempts before it's locked out (request a new one with verify/send).
| Field | Type | Required | Description |
|---|---|---|---|
| verification_id | string | Yes | Returned by verify/send |
| code | string | Yes | The code your customer entered |
Example request
curl -X POST https://app.6xcom.com/api/v1/verify/check \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"verification_id":"4821","code":"483920"}'Response
{
"success": true,
"status": "verified"
}Billing — SMS vs Voice work differently
SMS bills at your account's normal per-message SMS rate — no separate verification fee, it's priced identically to any other SMS you send.
Voice bills a flat fee per call attempt, charged the moment the call is placed, regardless of whether it's answered. This is intentionally different from a normal per-minute outbound call: a spoken verification code is a short, fixed-cost interaction, not a conversation you're billed by the minute for. The flat fee varies by destination country, same as any other rate.
Handling errors
Both endpoints also sit behind the standard API Authentication checks - a request can fail with 401 (missing/invalid token), 403 (inactive account or API Access addon not enabled), or 429 (daily limit or the 20/min send / 60/min check rate limit on these two routes specifically) before it even reaches verification logic. Within verification logic itself, both endpoints return HTTP 200 on success and 422 on any failure — always check the JSON body's success field rather than only the HTTP status. On verify/send failure, error is a human-readable message (insufficient balance, too many pending verifications for this number, no active extension for a voice call, destination not supported, etc). On verify/check, check status:
| status | Meaning |
|---|---|
| verified | Success — the code matched |
| not_found | Unknown verification_id, or it belongs to a different account |
| already_verified | This verification already succeeded once — verify/check is not re-checkable |
| expired | The 10-minute window passed — call verify/send again for a new code |
| max_attempts | 5 incorrect codes were submitted — call verify/send again for a new code |
| pending | Code was wrong, but attempts remain — attempts_remaining is included in the response |
Note: there's no email fallback here (unlike 6X's own signup verification) — we only have the phone number you submitted, not a customer email. If delivery isn't possible for that destination, verify/send returns an error you can surface to the customer.