HonkIOHonkIO

Verify

One-time codes by text message for Canadian phone numbers

Send a code by SMS, check the one your user types, and know the number is theirs. Two API calls, billed in Canadian dollars, with data stored in Canada.

Create a free account Read the Verify docs
Start a verification, then check the code
bash
curl -X POST https://api.honkio.ca/v1/verify \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "+1416XXXXXXX",
        "to": "+1613XXXXXXX",
        "app_name": "Acme" }'

curl -X POST https://api.honkio.ca/v1/verify/clxxx/check \
  -H "Authorization: Bearer mk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "000000" }'

How it works

Two calls: one sends the code, the other checks it.

  1. 1

    Start a verification

    Call POST /v1/verify with one of your numbers as from, your user's number as to and, if you like, your app's name. HonkIO texts a code and answers with the verification's id.

  2. 2

    Check the code

    Send the code your user typed to POST /v1/verify/:id/check. A right code answers verified; a wrong one answers with the number of attempts left.

  3. 3

    Use the confirmed number

    Mark the number as confirmed in your app. GET /v1/verify/:id reads a verification's status at any time, and GET /v1/verify lists them.

What is built in

The defaults are the safe ones. Change what your flow needs.

  • Codes of 4, 6 or 8 digits, 6 by default.
  • Codes expire after 10 minutes by default; set anything from 1 to 60 minutes.
  • Five wrong codes lock the verification, so a code cannot be guessed by trying them all.
  • One code per phone number per minute, so nobody can flood a phone with texts through your app.
  • Codes are kept only as a hash, and the text that carried a code is not stored.
  • Your app's name in the message, accepted only as plain text, so it can never carry a link.
  • A number that replied STOP to you is not texted, even for a code.
  • Errors in English and French, with stable codes such as VERIFICATION_EXPIRED and VERIFICATION_MAX_ATTEMPTS.
Every error code

What it costs

Prepaid, in CAD, from the same balance as your SMS.

  • $0.25per verification
  • $0.03per SMS segment for the text that carries the code
  • $2.50a month for a local number to send from

A code fits in one segment unless your app name is long or uses characters outside the standard SMS set. A verification the carrier refuses is refunded in full, and test verifications are free.

See every price

Canadian rules, handled

What HonkIO checks before a code goes out.

  • HonkIO treats a one-time code as a transactional message, so it does not ask for CASL consent before sending one. It still honours STOP: a number that opted out of your texts gets no code until it opts back in.
  • Codes go only to Canadian phone numbers. Any other number is refused with NON_CANADIAN_NUMBER before anything is charged.
  • Codes can come from a toll-free number once it is verified, and they do not need the double opt-in that other toll-free texts do.
  • Before your first live code, you confirm your own phone number, as for any live send.
  • Verifications are stored in Canada (AWS ca-central-1, Montréal). Requests are processed on US-hosted infrastructure before they are stored, as the privacy policy explains.
Read the privacy policy

Build it before you buy a number

Test mode runs the same checks and sends nothing.

With a test key (mk_test_...), nothing is sent and nothing is charged. The code is always zeros (000000 for six digits), and the from number can be any valid Canadian or US number, so you can build the whole flow before you top up or buy a number. Every verification says whether it was LIVE or TEST.

From your code or your agent

SDKs, the REST API and the MCP server.

The Node.js, Python, PHP and Laravel SDKs have Verify methods, the REST API takes plain JSON, and the HonkIO MCP server gives an AI agent tools to start and check codes.

SDK docsAI agents and MCP

Questions

Can Verify send codes by email or by voice call?
No. Verify sends codes by text message only, to Canadian phone numbers.
Do I need CASL consent before sending a code?
HonkIO treats a one-time code as a transactional message and does not check for CASL consent before sending it. It does check for STOP: a number that opted out of your texts gets no code until it opts back in. Commercial messages you send to the number later still need consent.
How much does a verification cost?
$0.25 per verification, plus $0.03 per SMS segment for the text that carries the code, in CAD, from your prepaid balance. A verification the carrier refuses is refunded in full, and test verifications are free.
Can I verify phone numbers outside Canada?
No. Verify sends only to Canadian numbers, and any other number is refused with NON_CANADIAN_NUMBER before anything is charged.
What happens after too many wrong codes?
After five wrong codes the verification is locked with VERIFICATION_MAX_ATTEMPTS and its code stops working. Start a new verification to send a fresh code; the same number can get a new one once a minute.
Do I need my own phone number?
For live codes, yes: the code is sent from one of your HonkIO numbers. A test key accepts any valid Canadian or US number as the sender, so you can build first and buy a number later.
Can I change the text of the message?
You choose the app name the message shows, up to 64 characters of plain text. The rest is fixed: the message gives the code, says when it expires and asks the person not to share it.

Related

  • SMS API

    Send and receive SMS with Canadian local and toll-free numbers, with CASL consent and STOP replies enforced in the API.

  • AI agents and MCP

    An MCP server that lets AI agents send SMS, run phone verification, buy Canadian numbers and check CASL consent through HonkIO.

  • SMS APIs in Canada compared

    SMS APIs for Canada compared on CASL, French opt-outs, where data is stored and pricing in CAD.

Try it in test mode first

Create a free account

Test keys work right after sign-up, with no card and no charges.