SMS

Phone numbers

Search for available Canadian numbers, provision one, and send from it. A live send needs a number your account owns.

Phone Numbers

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

Search takes active Canadian area codes (honkio.phoneNumbers.areaCodes() or GET /v1/phone-numbers/area-codes lists them by province) or a toll-free prefix, and is limited to 30 searches a minute. Provisioning needs a live key and charges the first month's rent plus a one-time activation fee, both shown on each search result and on GET /v1/pricing.

const { data: available, error } = await honkio.phoneNumbers.search({ areaCodes: '416' })
if (error) throw new Error(error.message)

// 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, ... }
for (const n of available) console.log(n.phone_number, n.upfront_cost_cents, n.monthly_cost_cents)

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
const { data: number, error } = await honkio.phoneNumbers.provision({ phoneNumber: '+14165550100' })
if (error) throw new Error(error.message)
console.log(number.id, number.phone_number)

# 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"}'

bash

# 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"

Buying a live number requires a verified mobile number.