Getting started

Quickstart

1. Create a free account — get live and test API keys instantly.
2. Record CASL consent for each phone number you'll message.
3. Optionally provision a Canadian long code number to send from.
4. Send your first message using the REST API.

Authentication

All API requests require a Bearer token in the Authorization header. Use test keys (mk_test_...) for development — no real SMS are sent, no charges. Use live keys (mk_live_...) for production.

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_code=416 \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

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

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": "+16135550199",
    "type": "express",
    "source_description": "Website opt-in form",
    "source_ip": "203.0.113.1"
  }'

Express consent never expires. Implied consent expires after 2 years per CASL §10(9).

Sending SMS

Send a message using a provisioned number. The API validates the Canadian destination number, checks CASL consent, and checks the DNCL before delivery.

curl -X POST https://api.honkio.ca/v1/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14165550100",
    "to":   "+16135550199",
    "body": "Hello from HonkIO! 🇨🇦"
  }'

Webhooks

Register a webhook endpoint to receive delivery receipts and inbound messages. Every payload is signed with HMAC-SHA256 — verify the X-HonkIO-Signature header.

{
  "id": "evt_01HXYZ...",
  "type": "message.delivered",
  "created_at": "2024-01-15T12:00:00Z",
  "data": {
    "message_id": "msg_01HXYZ...",
    "to": "+16135550199",
    "status": "delivered"
  }
}
// Header: X-HonkIO-Signature: sha256=...

Error codes