Verify

Start a phone number verification

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.

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

Request body

fromstring 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.

tostring required

The phone number to verify (E.164, Canadian numbers only)

code_length4 | 6 | 8

OTP digit length (default: 6)

ttl_minutesinteger

Minutes until the code expires (default: 10)

app_namestring

Brand name shown in the SMS body (default: HonkIO)

Response

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

idstring required
phone_numberstring required
from_numberstring required
status'pending' | 'verified' | 'expired' | 'max_attempts' required
attemptsinteger required
code_lengthinteger required
app_namestring 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_centsinteger required

Cost in cents CAD. On a TEST verification this is 0: nothing was charged.

expires_atstring date-time required
verified_atstring date-time nullable required
created_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.