API reference

Phone numbers

Provision and manage Canadian phone numbers.

get/v1/phone-numbers/area-codes

List provinces and their active area codes

Permissionphone_numbers:rNode.js SDKhonkio.phoneNumbers.areaCodes()

Requires phone_numbers:r.

Responses

200Provinces with their active area codes.
Field Type Description
data[]required object[]
provincerequired string
countryrequired string
area_codesrequired string[]
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.phoneNumbers.areaCodes()
if (error) throw new Error(error.message)
console.log(data.data)

curl https://api.honkio.ca/v1/phone-numbers/area-codes \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/phone-numbers/search

Search available Canadian phone numbers to provision

Permissionphone_numbers:rNode.js SDKhonkio.phoneNumbers.search()

Optionally filtered by area_codes: up to 25 distinct codes (repeats count once), each an active Canadian area code (GET /v1/phone-numbers/area-codes) or a toll-free prefix (833, 844, 855, 866, 877, 888). Toll-free prefixes are accepted although the area-code list does not include them: they are sold at the toll-free tier, and searching by prefix is how to find one. 1-800 numbers are not offered yet, so 800 is refused like an unknown code. More than 25 codes returns 422 TOO_MANY_AREA_CODES; any other code returns 422 VALIDATION_ERROR naming it in details.area_codes. Each account may search 30 times a minute; beyond that, 429 RATE_LIMITED with Retry-After.

Requires phone_numbers:r.

Parameters

Parameter	Type	Description
`area_codes`query	string	Comma-separated area codes to filter by (e.g. 416,647): at most 25, each an active Canadian area code or a toll-free prefix (833, 844, 855, 866, 877, 888)
`limit`query	integer	Minimum: 1 Maximum: 50 Default: 10

Responses

200Available numbers. A bare array, not wrapped in data.

Field	Type	Description
`phone_number`required	string	E.164
`country_code`required	string
`area_code`required	string	Can be null
`region`required	string	Province or territory, when the area code maps to one. Can be null
`capabilities`required	string[]
`monthly_cost_cents`required	integer	Recurring rent in CAD cents, at the tier (local or toll-free) this number would be sold at.
`upfront_cost_cents`required	integer	The first month's rent, charged when the number is provisioned.
`activation_fee_cents`required	integer	One-time activation fee charged with the first month. Not refunded on release.
`currency`required	string	One of: CAD

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
422VALIDATION_ERROR (details.area_codes names any code not sold) or TOO_MANY_AREA_CODES.The standard error body.
429RATE_LIMITED: 30 searches a minute per account, or 100 requests per second.The standard error body.
500Unexpected server error.The standard error body.
502NUMBER_SEARCH_FAILED: the carrier search failed.The standard error body.

Example

const { data: available, error } = await honkio.phoneNumbers.search({ areaCodes: ['416', '647'], limit: 5 })
if (error) throw new Error(error.message)
for (const n of available) console.log(n.phone_number, n.monthly_cost_cents)

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

get/v1/phone-numbers

List account's provisioned phone numbers

Permissionphone_numbers:rNode.js SDKhonkio.phoneNumbers.list()

Requires phone_numbers:r.

Responses

200The account's numbers, excluding released ones, newest first. Not paginated.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`phone_number`required	string	E.164
`area_code`required	string
`region`required	string	Province or territory, when the area code maps to one. Can be null
`capabilities`required	string[]
`status`required	string	One of: ACTIVE \| SUSPENDED \| RELEASING \| RELEASED
`monthly_cost_cents`required	integer	Recurring rent in CAD cents.
`provisioned_at`required	string	Format: date-time
`released_at`required	string	Format: date-time Can be null

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.phoneNumbers.list()
if (error) throw new Error(error.message)
for (const n of data.data) console.log(n.phone_number, n.status)

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

post/v1/phone-numbers

Provision (purchase) a phone number

Permissionphone_numbers:wNode.js SDKhonkio.phoneNumbers.provision()

Provisions a number and debits its first month's rent plus a one-time activation fee, as one purchase (see GET /v1/pricing for both amounts; the activation fee is the same on every tier and is not refunded on release). A balance that cannot cover the total returns 402 INSUFFICIENT_BALANCE before anything is charged or ordered. Accounts are capped on how many phone numbers they may hold at once (counting ACTIVE and SUSPENDED), a per-account limit that falls back to a platform-wide default staff can change at runtime; exceeding it returns 403 NUMBER_LIMIT_REACHED with the limit and current usage in details. Request a higher allowance from the dashboard. May also return 409 PURCHASE_IN_PROGRESS when another purchase for this account is already in flight: this is transient, unlike the terminal 409 CONFLICT returned when the number is already owned; retry PURCHASE_IN_PROGRESS after a short delay rather than treating it as a failed purchase.

Requires phone_numbers:w.

Request body

Field	Type	Description
`phone_number`required	string	E.164 number to provision (from available search)

Responses

201The provisioned number.

Field	Type	Description
`id`required	string
`phone_number`required	string	E.164
`area_code`required	string
`region`required	string	Province or territory, when the area code maps to one. Can be null
`capabilities`required	string[]
`status`required	string	One of: ACTIVE \| SUSPENDED \| RELEASING \| RELEASED
`monthly_cost_cents`required	integer	Recurring rent in CAD cents.
`provisioned_at`required	string	Format: date-time
`released_at`required	string	Format: date-time Can be null

401Missing, invalid, revoked or expired API key.The standard error body.
402INSUFFICIENT_BALANCE: the balance cannot cover the first month and the activation fee. Nothing was charged or ordered.The standard error body.
403NUMBER_LIMIT_REACHED (details carries limit and used), LIVE_KEY_REQUIRED (test keys cannot provision), or ACCOUNT_NOT_VERIFIED (the account has not verified an owner mobile number).The standard error body.
409CONFLICT (the number is already owned) or PURCHASE_IN_PROGRESS (another purchase for this account is in flight; retry shortly).The standard error body.
422NON_CANADIAN_NUMBER or VALIDATION_ERROR.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500INTERNAL_ERROR: the charge failed for a reason other than balance.The standard error body.
501TOLLFREE_800_COMING_SOON: 1-800 numbers are not offered yet.The standard error body.
502PROVISIONING_FAILED: the carrier did not provision the number. The charge is refunded.The standard error body.

Example

const { data: number, error } = await honkio.phoneNumbers.provision({ phoneNumber: '+1416XXXXXXX' })
if (error) throw new Error(error.message)
console.log(number.id, number.status)

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": "+1613XXXXXXX"
  }'

get/v1/phone-numbers/{id}

Get a phone number by ID

Permissionphone_numbers:rNode.js SDKhonkio.phoneNumbers.get()

Requires phone_numbers:r.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

200The number, released ones included.

Field	Type	Description
`id`required	string
`phone_number`required	string	E.164
`area_code`required	string
`region`required	string	Province or territory, when the area code maps to one. Can be null
`capabilities`required	string[]
`status`required	string	One of: ACTIVE \| SUSPENDED \| RELEASING \| RELEASED
`monthly_cost_cents`required	integer	Recurring rent in CAD cents.
`provisioned_at`required	string	Format: date-time
`released_at`required	string	Format: date-time Can be null

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

const { data, error } = await honkio.phoneNumbers.get('NUMBER_ID')
if (error) throw new Error(error.message)
console.log(data.phone_number, data.status)

curl https://api.honkio.ca/v1/phone-numbers/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

delete/v1/phone-numbers/{id}

Release (cancel) a phone number

Permissionphone_numbers:dNode.js SDKhonkio.phoneNumbers.release()

Releases the number at the carrier and answers 204, also when the carrier had already let it go. If the carrier does not accept the release, answers 502 RELEASE_FAILED and the number stays yours, unchanged; try again.

Requires phone_numbers:d.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

204Released, or already released at the carrier.
401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403LIVE_KEY_REQUIRED: test keys cannot reach live resources here. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
404NOT_FOUND: no such number on this account, or it is already released.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.
502RELEASE_FAILED: the carrier did not accept the release. The number stays yours, unchanged; try again.The standard error body.

Example

const { error } = await honkio.phoneNumbers.release('NUMBER_ID')
if (error) throw new Error(error.message)

curl -X DELETE https://api.honkio.ca/v1/phone-numbers/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/phone-numbers/allowance-requests

List your phone number allowance requests

Permissionphone_numbers:r

Requires phone_numbers:r.

Responses

200The account's allowance requests, newest first.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`requested_limit`required	integer	Total numbers asked for, not an increment.
`limit_at_request`required	integer
`held_at_request`required	integer
`reason`required	string
`status`required	string	One of: PENDING \| APPROVED \| DENIED
`granted_limit`required	integer	Can be null
`staff_note`required	string	Can be null
`decided_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403The API key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
429Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

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

post/v1/phone-numbers/allowance-requests

Request a higher phone number allowance

Permissionphone_numbers:w

Files a request for HonkIO staff to review. Only one request may be pending at a time. Approval raises the account limit; you are emailed when that happens.

Requires phone_numbers:w.

Request body

Field	Type	Description
`requested_limit`required	integer	Total numbers you want to be able to hold (not an increment) Minimum: 2 Maximum: 100
`reason`required	string	What you need them for. Staff decide on this. At least 10 characters At most 1000 characters

Responses

201The request, pending review.

Field	Type	Description
`id`required	string
`requested_limit`required	integer	Total numbers asked for, not an increment.
`limit_at_request`required	integer
`held_at_request`required	integer
`reason`required	string
`status`required	string	One of: PENDING \| APPROVED \| DENIED
`granted_limit`required	integer	Can be null
`staff_note`required	string	Can be null
`decided_at`required	string	Format: date-time Can be null
`created_at`required	string	Format: date-time

401Missing, invalid, revoked or expired API key.The standard error body.
402The account has no balance, or a LIVE key was used before the first top-up.The standard error body.
403LIVE_KEY_REQUIRED: test keys cannot reach live resources here. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.The standard error body.
409ALLOWANCE_REQUEST_PENDING: a request is already pending.The standard error body.
422VALIDATION_ERROR, or INVALID_ALLOWANCE_REQUEST when requested_limit is not above the current limit.The standard error body.
429RATE_LIMITED: 3 requests per day per account.The standard error body.
500Unexpected server error.The standard error body.

Example

cURL

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": 2,
    "reason": "..."
  }'

Field	Type	Description
`data[]`required	object[]
`province`required	string
`country`required	string
`area_codes`required	string[]