---
title: "Start a phone number verification"
method: POST
path: "/v1/verify"
tags: ["Verify"]
---

# Start a phone number verification

`POST /v1/verify`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/verify`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Sends an OTP to the specified Canadian phone number.

Billed at your standard per-part message rate (the OTP is one part unless `app_name` is long or uses non-GSM characters; the charge is settled to the carrier's part count) plus a per-verification upcharge: see `verification_upcharge_cents` from `GET /v1/pricing`. A verification the carrier rejects is refunded in full.

**Options:**
- `code_length`: digits in the OTP, `4`, `6` (default), or `8`
- `ttl_minutes`: how long the code is valid (1 to 60 min, default 10)
- `app_name`: brand name shown in the SMS, e.g. `"Acme"` → *"Your Acme verification code is: …"*

In test mode (`mk_test_...` key) no SMS is sent; the code is always all zeros for the chosen length (e.g. `000000` for 6-digit, `0000` for 4-digit). `from` may be any valid NANP number in test mode, so an account with no number yet can try it; a toll-free `from` must still be yours and verified.

Requires `verify:w`.

## Request body

- object
  - `from` string, required: Your HonkIO number (E.164, must be active on your account). A test key may use any valid NANP number, except a toll-free one, which must be yours and verified in both modes.
  - `to` string, required: The phone number to verify (E.164, Canadian numbers only)
  - `code_length` 4 | 6 | 8: OTP digit length (default: 6)
  - `ttl_minutes` integer: Minutes until the code expires (default: 10)
  - `app_name` string: Brand name shown in the SMS body (default: HonkIO)

## Response `201`

Verification started: the code was sent (LIVE) or simulated (TEST, code all zeros).

- Verification: A phone-number verification (SMS OTP). status is lowercase, unlike message statuses.
  - `id` string, required
  - `phone_number` string, required
  - `from_number` string, required
  - `status` 'pending' | 'verified' | 'expired' | 'max_attempts', required
  - `attempts` integer, required
  - `code_length` integer, required
  - `app_name` string, nullable, required
  - `mode` 'LIVE' | 'TEST', required: TEST verifications are simulated: no SMS is sent, nothing is billed, and the code is always 000000 padded to code_length.
  - `cost_cents` integer, required: Cost in cents CAD. On a TEST verification this is 0: nothing was charged.
  - `expires_at` string, date-time, required
  - `verified_at` string, date-time, nullable, required
  - `created_at` string, date-time, required

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: INSUFFICIENT_BALANCE: the balance cannot cover the send. Also PAYMENT_REQUIRED when a LIVE key is used before the first top-up.
- `403`: ACCOUNT_NOT_VERIFIED, PHONE_NUMBER_NOT_OWNED, ALLOW_LIST_BLOCKED, DENY_LIST_BLOCKED, SENDING_PAUSED, or TOLL_FREE_NOT_VERIFIED (a toll-free from number without an approved toll-free verification; test keys too).
- `422`: VALIDATION_ERROR, NON_CANADIAN_NUMBER, RESERVED_DESTINATION, UNDELIVERABLE_NUMBER, NOT_A_MOBILE_NUMBER or LINK_SHORTENER_BLOCKED. A refused start costs nothing.
- `429`: RATE_LIMITED (one start per recipient per 60 seconds, Retry-After 60), DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_RATE_LIMITED or RECIPIENT_RATE_LIMITED.
- `451`: OPT_OUT_BLOCKED: the recipient opted out.
- `500`: Unexpected server error.
- `502`: CARRIER_ERROR: the carrier refused the SMS. The charge is refunded.
- `503`: CARRIER_UNAVAILABLE: the carrier could not be reached. Nothing was sent or charged; retry shortly. CARRIER_THROTTLED: the carrier asked us to slow down and did not take the code. Nothing was charged; start again after Retry-After. CARRIER_TIMEOUT: the carrier did not answer in time, so the code may or may not have reached the recipient. The verification is closed, so that code can never be checked, and the charge is refunded: start a new one.

---

[API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)