SMS API

Quickstart

1. Create a free account, then open API Keys → Create key in the dashboard. The full key is shown once, right after you create it, so copy it then.
2. Start with a test key: it works immediately, before any top-up, so you can send test messages and explore the API for free.
3. Top up your balance with a card via Stripe. Live keys return 402 PAYMENT_REQUIRED until the first top-up.
4. Verify your phone number as the account owner. A live send needs a verified owner phone.
5. Buy a Canadian number to send from; a live send needs a number your account owns.
6. Record CASL consent for each phone number you will message.
7. Send your first message using the REST API.

Phone Numbers

Search for available Canadian numbers, provision one, and use it as the from field when sending.

curl https://api.honkio.ca/v1/phone-numbers/search?area_codes=416 \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

# Response 200 (per result): what buying it charges now and monthly, in CAD cents
# { "phone_number": "+14165550100", "region": "Ontario",
#   "upfront_cost_cents": 250, "activation_fee_cents": 100, "monthly_cost_cents": 250, ... }

# Provision a number
curl -X POST https://api.honkio.ca/v1/phone-numbers \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+14165550100"}'

# Accounts hold a limited number of numbers. GET /v1/accounts/me reports
# phone_number_limit and phone_numbers_used: check them before buying, or
# handle the 403 NUMBER_LIMIT_REACHED that a purchase past the cap returns.

# Ask HonkIO staff to raise the limit. One request may be pending at a time.
curl -X POST https://api.honkio.ca/v1/phone-numbers/allowance-requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requested_limit": 10, "reason": "Onboarding three new clinics this quarter"}'

# Response 201: { "status": "PENDING", "requested_limit": 10, ... }
# You are emailed if it is approved; the decision also shows in the dashboard.

# Check on it
curl https://api.honkio.ca/v1/phone-numbers/allowance-requests \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

CASL Consent (required before sending)

Under CASL, you must record consent before sending a commercial message to any recipient. The API will block sends to phone numbers without valid consent (HTTP 451).

curl -X POST https://api.honkio.ca/v1/compliance/consents \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX",
    "consent_type": "express",
    "source_description": "Website opt-in form",
    "source_ip": "203.0.113.1"
  }'

Implied consent for an existing customer, with the clock running from their last transaction:

curl -X POST https://api.honkio.ca/v1/compliance/consents \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1613XXXXXXX",
    "consent_type": "implied",
    "relationship_type": "purchase",
    "last_transaction_date": "2025-11-04"
  }'

# → { "status": "recorded", "phone_number": "+1613XXXXXXX", "expires_at": "2027-11-04T00:00:00.000Z" }

Express consent never expires. Implied consent expires after 2 years per CASL §10(9). Pass last_transaction_date so the two-year clock runs from the real relationship rather than from the day you record it, or set expires_at outright when you have already worked out the expiry. The response echoes expires_at so you can verify it.

Sending SMS

Send a message using a provisioned number. The API validates the Canadian destination number, and checks CASL consent before delivery (CRTC DNCL checking coming soon).

# "from" is one of your HonkIO numbers; "to" is a real number you hold consent for
curl -X POST https://api.honkio.ca/v1/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1416XXXXXXX",
    "to":   "+1613XXXXXXX",
    "body": "Hello from HonkIO! 🇨🇦"
  }'

Phone Number Verification (OTP)

Use the Verify API to confirm ownership of a phone number before sending commercial messages. Your end-user receives a one-time code via SMS; submit it to the check endpoint to confirm.

# Start a verification (sends OTP SMS)
curl -X POST https://api.honkio.ca/v1/verify   -H "Authorization: Bearer mk_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "from": "+1416XXXXXXX",
    "to":   "+1613XXXXXXX",
    "code_length": 6,
    "ttl_minutes": 10,
    "app_name": "Acme"
  }'
# Response: { "id": "clxxx...", "status": "pending", "code_length": 6, ... }

# Check the code submitted by your user
curl -X POST https://api.honkio.ca/v1/verify/clxxx.../check   -H "Authorization: Bearer mk_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{ "code": "483721" }'
# Response 200: { "status": "verified", ... }
# Response 422: { "code": "VERIFICATION_INVALID_CODE", "attempts_remaining": 4 }

# Fetch status at any time
curl https://api.honkio.ca/v1/verify/clxxx...   -H "Authorization: Bearer mk_live_YOUR_KEY"

In test mode the code is always all zeros for the chosen length (e.g. 000000 for 6-digit). No SMS is sent and nothing is billed. Every verification returns a "mode" field of "LIVE" or "TEST" so you can tell a simulated verification from a real one.

Pricing

Prices are set at runtime and can change without a release, so read them rather than hardcoding them. All amounts are CAD cents. Sending is billed per SMS part: message_cost_cents × the parts the carrier splits the body into. Parts are counted the way the carrier counts them: typographic quotes, dashes and ellipses are smart-encoded to GSM-7 (160 characters, then 153 per part), while emoji and most accented letters force Unicode parts (70, then 67). The charge is settled to the carrier's part count after the send. A message the carrier rejects outright costs nothing, and so does a send to a reserved exchange (555-XXXX and similar), which is refused here; a message the carrier accepts but cannot deliver keeps its charge. A body over 10 parts is refused with 422 MESSAGE_TOO_LONG before any charge. verification_cost_cents covers a typical single-part OTP; a long or non-GSM app_name can add a part. phone_number_activation_fee_cents is charged once, together with the first month, on every number provisioned, local or toll-free, and is not refunded on release. inbound_message_cost_cents is charged per part of every SMS received on a provisioned number, sender and carrier included, except STOP, START and HELP keywords; a received message is debited even if it takes the balance below zero, which pauses sending until the next top-up.

# Current prices, in CAD cents
curl https://api.honkio.ca/v1/pricing \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

# Response 200:
# {
#   "message_cost_cents": 3,
#   "verification_upcharge_cents": 25,
#   "verification_cost_cents": 28,
#   "phone_number_upfront_cost_cents": 250,
#   "phone_number_monthly_cost_cents": 250,
#   "phone_number_activation_fee_cents": 100,
#   "inbound_message_cost_cents": 3
# }

Test-mode requests are priced identically in the response but never charged, so you can see what an integration would cost before spending anything.

Sending limits

HonkIO is built for transactional and relationship messaging, not campaigns, and every customer’s deliverability rides on a shared carrier profile. These limits keep bulk marketing off the platform; a clinic, a contractor or a SaaS sending codes will not notice them. The sending limits apply to live mode only; the link-shortener rule, the reserved and undeliverable destination checks, and the broadcast group-size cap run in both modes.

• Daily cap: new accounts can send 250 live messages per rolling 24 hours. It does not lift on its own. 30 days after your first live message you can request a higher volume from the dashboard; approval sets 1,000 a day or the figure you asked for. Refused sends return 429 DAILY_LIMIT_REACHED with your limit and count.
• Identical messages: the same body may reach at most 250 distinct recipients per 24 hours (429 FANOUT_LIMIT_REACHED). Personalized messages are unaffected.
• Per-number rate: 60 messages per minute per sending number, which is what Canadian carriers grant a long code anyway (429 NUMBER_RATE_LIMITED with Retry-After).
• Broadcasts: up to 250 recipients per contact-group broadcast and 3 broadcasts per 24 hours (422 BROADCAST_TOO_LARGE, 429 BROADCAST_LIMIT_REACHED).
• Link shorteners (bit.ly, tinyurl and similar) are refused in both modes because carriers filter them (422 LINK_SHORTENER_BLOCKED). Use the full URL.
• Delivery warning, then automatic pause: if more than 10% of your last 50 live messages fail at the carrier, you are emailed (and account.delivery_warning fires) without any pause. If more than 1% of recipients reply STOP, or more than 5% of messages are rejected by carriers, over your recent sends, live sending pauses for 24 hours and you are emailed (403 SENDING_PAUSED with the resume time; account.sending_paused fires).
• Top-ups: the balance cannot exceed $500 and top-ups are limited to $1,000 per 30 days. Raised on request.
• Per-recipient cap: 30 messages to one recipient per hour and 100 per 24 hours (429 RECIPIENT_RATE_LIMITED with Retry-After). A two-way conversation never gets near it; a script retrying one number does.
• Undelivered messages are billed: a message the carrier accepts but cannot deliver keeps its charge. A reserved exchange (555-XXXX, N11 exchanges such as 411 or 911, carrier test codes, exchanges starting with 0 or 1) is refused for free with 422 RESERVED_DESTINATION, in test mode too, and a reserved area code (555, 911 and the like) as non-Canadian. Anything that retries should send an Idempotency-Key header so a retry can never become a second charge. An hour of unusual spend triggers an email and account.spend_warning.
• Undeliverable numbers: after 3 consecutive carrier failures to one number within 30 days, from any HonkIO customer, sends to it are refused without charge (422 UNDELIVERABLE_NUMBER with the failure count, when it was listed and when it expires) for 90 days, then retried in case the number was reassigned.

curl https://api.honkio.ca/v1/send-limit \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

# → { "daily_limit": 250, "sent_last_24h": 12, "remaining": 238,
#     "recipient_rate_per_hour": 30, "recipient_rate_per_day": 100,
#     "probation": { "ends_at": "2026-09-26T14:02:11.000Z", "eligible_to_request": false },
#     "paused_until": null, "requests": [] }

Read your current limits and usage with GET /v1/send-limit, and file a request with POST /v1/send-limit/requests. Every figure above is a platform default that can be raised per account.

Webhook events

These are the SMS, opt-out and phone number events. Registering an endpoint, the envelope every event arrives in, retries and signatures are covered under Platform webhooks.

Every payload is signed with HMAC-SHA256, so verify the X-HonkIO-Signature header. A message.received event carries the sender, your number, the body, keyword_action (STOP/START handling), and the segment_count and cost_cents the message was billed at. A message.sent event carries carrier_message_id, the id the carrier assigned to the message, with the same two billing fields.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.delivered",
  "created": "2026-09-19T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "delivered",
    "message_status": "DELIVERED",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": []
  }
}
// Headers: X-HonkIO-Signature, X-HonkIO-Timestamp, X-HonkIO-Event

A message id can emit message.failed (only when the failure was CARRIER_UNAVAILABLE; an INSUFFICIENT_BALANCE failure fires no webhook) and later message.queued again, then message.sent, when a retry with the same Idempotency-Key re-attempts a message that failed before it reached the carrier.

Every event, as your endpoint receives it. The examples are redacted: ids, numbers and addresses are placeholders. Fields can be added over time, so ignore any you do not recognise.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.queued",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX",
    "status": "QUEUED",
    "message_status": "QUEUED"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.sending",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "sending",
    "message_status": "SENDING",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": []
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.sent",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX",
    "status": "SENDING",
    "message_status": "SENDING",
    "carrier_message_id": "40319xxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "segment_count": 1,
    "cost_cents": 3
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.delivered",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "delivered",
    "message_status": "DELIVERED",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": []
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.failed",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1416XXXXXXX",
    "to": "+1613XXXXXXX",
    "status": "FAILED",
    "message_status": "FAILED",
    "error_code": "INVALID_PHONE_NUMBER",
    "error_message": "The destination is not a valid phone number."
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.undelivered",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "status": "delivery_failed",
    "message_status": "UNDELIVERED",
    "to": "+1613XXXXXXX",
    "from": "+1416XXXXXXX",
    "errors": [
      {
        "code": "40002",
        "title": "Blocked as spam",
        "detail": "The destination carrier blocked the message."
      }
    ]
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "message.received",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "message_id": "clxxxmessagexxxxxxxxxxxxx",
    "from": "+1613XXXXXXX",
    "to": "+1416XXXXXXX",
    "body": "Yes, see you at 3",
    "keyword_action": "ignored",
    "segment_count": 1,
    "cost_cents": 1,
    "message_status": "RECEIVED"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "opt_out.recorded",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1613XXXXXXX",
    "from_number": "+1416XXXXXXX",
    "keyword": "STOP"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "opt_out.reinstated",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1613XXXXXXX",
    "from_number": "+1416XXXXXXX",
    "keyword": "START"
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "phone_number.suspended",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1416XXXXXXX",
    "reason": "insufficient_balance",
    "monthly_cost_cents": 299
  }
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "phone_number.released",
  "created": "2026-09-24T12:00:00.000Z",
  "account_id": "clxxxaccountxxxxxxxxxxxxx",
  "livemode": true,
  "data": {
    "phone_number": "+1416XXXXXXX",
    "reason": "customer_released"
  }
}

Error codes

The codes below are specific to SMS, phone numbers, verification and CASL. Any call can also answer with the general codes in the platform error table, such as VALIDATION_ERROR, INSUFFICIENT_BALANCE and NOT_FOUND.