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
`number_type`required	string	Toll-free numbers (833, 844, 855, 866, 877, 888) need an approved toll-free verification before they can send SMS. One of: local \| toll_free
`toll_free_verification`required	object	The newest toll-free verification application for this number, cancelled ones aside. Null for a local number or a toll-free number never applied for. Can be null
`id`required	string	tfv_…
`status`required	string	The number sends SMS once this is APPROVED. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED

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, and rent owed on a number released while suspended returns 402 RENT_OWED, 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
`number_type`required	string	Toll-free numbers (833, 844, 855, 866, 877, 888) need an approved toll-free verification before they can send SMS. One of: local \| toll_free
`toll_free_verification`required	object	The newest toll-free verification application for this number, cancelled ones aside. Null for a local number or a toll-free number never applied for. Can be null
`id`required	string	tfv_…
`status`required	string	The number sends SMS once this is APPROVED. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED

401Missing, invalid, revoked or expired API key.The standard error body.
402INSUFFICIENT_BALANCE: the balance cannot cover the first month and the activation fee. RENT_OWED: rent is owed on a number released while suspended; top up to pay it first. 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), PURCHASE_IN_PROGRESS (another purchase for this account is in flight; retry shortly), or COMPED_TOLL_FREE (toll-free numbers are not available on this account).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
`number_type`required	string	Toll-free numbers (833, 844, 855, 866, 877, 888) need an approved toll-free verification before they can send SMS. One of: local \| toll_free
`toll_free_verification`required	object	The newest toll-free verification application for this number, cancelled ones aside. Null for a local number or a toll-free number never applied for. Can be null
`id`required	string	tfv_…
`status`required	string	The number sends SMS once this is APPROVED. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED

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. Releasing a SUSPENDED number leaves one month of its rent owed (rent_owed_cents on the account): until a top-up pays it, paid sends and number purchases are refused with 402 RENT_OWED.

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

Needs a verified business (BUSINESS_VERIFICATION_REQUIRED until then; see /v1/business-verification). 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.
403BUSINESS_VERIFICATION_REQUIRED: verify your business first (PUT /v1/business-verification, then submit it). Also LIVE_KEY_REQUIRED for a test key, or FORBIDDEN when the key lacks the permission this operation requires.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": "..."
  }'

get/v1/toll-free-verifications/options

List toll-free verification options

Permissionphone_numbers:rNode.js SDKhonkio.tollFreeVerifications.options()

The values an application's use_case, monthly_volume, entity_type and business_address.province take, each with an English and French label, and the verification fee.

Requires phone_numbers:r.

Responses

200The option lists and the fee.

Field	Type	Description
`use_cases[]`required	object[]
`value`required	string
`label_en`required	string
`label_fr`required	string
`monthly_volumes[]`required	object[]
`value`required	string
`label_en`required	string
`label_fr`required	string
`entity_types[]`required	object[]
`value`required	string
`label_en`required	string
`label_fr`required	string
`provinces[]`required	object[]
`value`required	string
`label_en`required	string
`label_fr`required	string
`fee_cents`required	integer	The verification fee, in cents CAD, charged once per application.

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: options, error } = await honkio.tollFreeVerifications.options()
if (error) throw new Error(error.message)
for (const u of options.use_cases) console.log(u.value, u.label_en)
console.log(options.fee_cents)

curl https://api.honkio.ca/v1/toll-free-verifications/options \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

get/v1/toll-free-verifications

List toll-free verification applications

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

The account's applications, newest first, cancelled ones included. Not paginated.

Requires phone_numbers:r.

Parameters

Parameter	Type	Description
`status`query	string	Only applications in this status. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED \| CANCELLED

Responses

200The account's applications, newest first.

Field	Type	Description
`data[]`required	object[]
`id`required	string
`status`required	string	DRAFT, then AWAITING_PAYMENT, IN_REVIEW (HonkIO staff), SUBMITTED (with the carrier) and APPROVED. CHANGES_REQUESTED and REJECTED (by the carrier) can be edited and submitted again, and a REJECTED one can be withdrawn (CANCELLED); DECLINED (by HonkIO) and CANCELLED are final. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED \| CANCELLED
`phone_numbers[]`required	object[]
`id`required	string
`phone_number`required	string
`application`required	object	The application as stored: every field, with the business number, postal code and phone normalized.
`business_name`required	string
`doing_business_as`required	string	Can be null
`entity_type`required	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string
`business_address`required	object
`line1`required	string
`city`required	string
`province`required	string
`postal_code`required	string
`contact`required	object
`first_name`required	string
`last_name`required	string
`email`required	string
`phone`required	string
`website`required	string
`use_case`required	string	One of: 2FA \| App Notifications \| Appointments \| Auctions \| Auto Repair Services \| Bank Transfers \| Billing \| Booking Confirmations \| Business Updates \| COVID-19 Alerts \| Career Training \| Chatbot \| Conversational / Alerts \| Courier Services & Deliveries \| Emergency Alerts \| Events & Planning \| Financial Services \| Fraud Alerts \| Fundraising \| General Marketing \| General School Updates \| HR / Staffing \| Healthcare Alerts \| Housing Community Updates \| Insurance Services \| Job Dispatch \| Legal Services \| Mixed \| Motivational Reminders \| Notary Notifications \| Order Notifications \| Political \| Public Works \| Real Estate Services \| Religious Services \| Repair and Diagnostics Alerts \| Rewards Program \| Surveys \| System Alerts \| Voting Reminders \| Waitlist Alerts \| Webinar Reminders \| Workshop Alerts
`use_case_summary`required	string
`sample_messages`required	string[]
`opt_in_workflow`required	string
`opt_in_image_urls`required	string[]
`opt_in_confirmation_message`required	string
`help_message`required	string
`privacy_policy_url`required	string
`terms_url`required	string	Can be null
`monthly_volume`required	string	One of: 10 \| 100 \| 1,000 \| 10,000 \| 100,000 \| 250,000 \| 500,000 \| 750,000 \| 1,000,000 \| 5,000,000 \| 10,000,000+
`age_gated`required	boolean
`additional_information`required	string	Can be null
`fee_cents`required	integer	The verification fee for this application, in cents CAD.
`payment_url`required	string	While AWAITING_PAYMENT: the dashboard page where the fee is paid. Null otherwise. Can be null
`paid_at`required	string	Format: date-time Can be null
`refunded_at`required	string	Format: date-time Can be null
`reviewer_note`required	string	What HonkIO staff asked to change, or why they declined the application. Can be null
`carrier_status`required	string	Where the carrier's review stands once it has the application: pending, action_needed (the carrier asked HonkIO a question; nothing for you to do yet), approved or rejected. Null before it is submitted. One of: pending \| action_needed \| approved \| rejected Can be null
`carrier_rejection_reason`required	string	Why the carrier rejected the application, when it did. Can be null
`submitted_at`required	string	Format: date-time Can be null
`decided_at`required	string	When the carrier approved or rejected it. Format: date-time Can be null
`created_at`required	string	Format: date-time
`updated_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

const { data, error } = await honkio.tollFreeVerifications.list({ status: 'CHANGES_REQUESTED' })
if (error) throw new Error(error.message)
for (const v of data.data) console.log(v.id, v.reviewer_note)

curl https://api.honkio.ca/v1/toll-free-verifications \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/toll-free-verifications

Create a toll-free verification application

Permissionphone_numbers:wNode.js SDKhonkio.tollFreeVerifications.create()

Toll-free numbers can send SMS only once verified. This creates a DRAFT application for up to 5 of your toll-free numbers; submit it to pay the verification fee and send it for review. Live keys only.

Requires phone_numbers:w.

Request body

The numbers to verify and the application for them.

Field	Type	Description
`phone_number_ids`required	string[]	The ids of 1 to 5 of your toll-free numbers (GET /v1/phone-numbers). A number can be on only one open application.
`application`required	object	The application. Every field is checked when you create it.
`business_name`required	string	The legal name of the business, as registered with the Canada Revenue Agency. At least 1 characters At most 255 characters
`doing_business_as`	string	The name the business trades under, when it differs from the legal name. At most 255 characters Can be null
`entity_type`required	string	The kind of organization. GET /v1/toll-free-verifications/options lists the values with labels. One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string	The CRA business number: 9 digits, optionally followed by a program account such as RC0001. Spaces and hyphens are ignored. At most 40 characters
`business_registration_type`	string	Optional. Always CRA: only Canadian businesses can apply. One of: CRA
`business_registration_country`	string	Optional. Always CA. One of: CA
`business_address`required	object	The registered address of the business, in Canada.
`line1`required	string	At least 1 characters At most 255 characters
`city`required	string	At least 1 characters At most 100 characters
`province`required	string	Two-letter province or territory code. One of: AB \| BC \| MB \| NB \| NL \| NS \| NT \| NU \| ON \| PE \| QC \| SK \| YT
`postal_code`required	string	Canadian postal code, e.g. K1A 0B1. At most 10 characters
`contact`required	object	The person the carrier and HonkIO staff can contact about this application.
`first_name`required	string	At least 1 characters At most 100 characters
`last_name`required	string	At least 1 characters At most 100 characters
`email`required	string	Format: email At most 254 characters
`phone`required	string	A North American phone number, e.g. +14165550100. At most 32 characters
`website`required	string	The business website (https). Reviewers check that it matches the business. At most 2048 characters
`use_case`required	string	What the messages are for. GET /v1/toll-free-verifications/options lists the values with labels. One of: 2FA \| App Notifications \| Appointments \| Auctions \| Auto Repair Services \| Bank Transfers \| Billing \| Booking Confirmations \| Business Updates \| COVID-19 Alerts \| Career Training \| Chatbot \| Conversational / Alerts \| Courier Services & Deliveries \| Emergency Alerts \| Events & Planning \| Financial Services \| Fraud Alerts \| Fundraising \| General Marketing \| General School Updates \| HR / Staffing \| Healthcare Alerts \| Housing Community Updates \| Insurance Services \| Job Dispatch \| Legal Services \| Mixed \| Motivational Reminders \| Notary Notifications \| Order Notifications \| Political \| Public Works \| Real Estate Services \| Religious Services \| Repair and Diagnostics Alerts \| Rewards Program \| Surveys \| System Alerts \| Voting Reminders \| Waitlist Alerts \| Webinar Reminders \| Workshop Alerts
`use_case_summary`required	string	A few sentences on what you send, to whom, and why they expect it. At least 10 characters At most 2000 characters
`sample_messages`required	string[]	1 to 5 messages exactly as you will send them, at most 1000 characters together. At least one must tell the recipient how to opt out (STOP, or ARRET in French).
`opt_in_workflow`required	string	How recipients agree to receive your messages: where, how, and what they are told. At least 10 characters At most 2000 characters
`opt_in_image_urls`required	string[]	1 to 5 https links to screenshots or photos of the opt-in (a web form, a paper form, a checkout box). The carrier requires at least one.
`opt_in_confirmation_message`required	string	The message a recipient gets right after opting in. At least 1 characters At most 1000 characters
`help_message`required	string	The reply to HELP: who you are and how to reach you. At least 1 characters At most 1000 characters
`privacy_policy_url`required	string	Your privacy policy (https). At most 2048 characters
`terms_url`	string	Your terms of service (https), if you have them. At most 2048 characters Can be null
`monthly_volume`required	string	The number of messages you expect to send a month. GET /v1/toll-free-verifications/options lists the values with labels. One of: 10 \| 100 \| 1,000 \| 10,000 \| 100,000 \| 250,000 \| 500,000 \| 750,000 \| 1,000,000 \| 5,000,000 \| 10,000,000+
`age_gated`	boolean	True when the messages are about age-restricted products such as alcohol or cannabis.
`additional_information`	string	Anything else the reviewers should know. At most 2000 characters Can be null

Responses

201The application, in DRAFT.

Field	Type	Description
`id`required	string
`status`required	string	DRAFT, then AWAITING_PAYMENT, IN_REVIEW (HonkIO staff), SUBMITTED (with the carrier) and APPROVED. CHANGES_REQUESTED and REJECTED (by the carrier) can be edited and submitted again, and a REJECTED one can be withdrawn (CANCELLED); DECLINED (by HonkIO) and CANCELLED are final. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED \| CANCELLED
`phone_numbers[]`required	object[]
`id`required	string
`phone_number`required	string
`application`required	object	The application as stored: every field, with the business number, postal code and phone normalized.
`business_name`required	string
`doing_business_as`required	string	Can be null
`entity_type`required	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string
`business_address`required	object
`line1`required	string
`city`required	string
`province`required	string
`postal_code`required	string
`contact`required	object
`first_name`required	string
`last_name`required	string
`email`required	string
`phone`required	string
`website`required	string
`use_case`required	string	One of: 2FA \| App Notifications \| Appointments \| Auctions \| Auto Repair Services \| Bank Transfers \| Billing \| Booking Confirmations \| Business Updates \| COVID-19 Alerts \| Career Training \| Chatbot \| Conversational / Alerts \| Courier Services & Deliveries \| Emergency Alerts \| Events & Planning \| Financial Services \| Fraud Alerts \| Fundraising \| General Marketing \| General School Updates \| HR / Staffing \| Healthcare Alerts \| Housing Community Updates \| Insurance Services \| Job Dispatch \| Legal Services \| Mixed \| Motivational Reminders \| Notary Notifications \| Order Notifications \| Political \| Public Works \| Real Estate Services \| Religious Services \| Repair and Diagnostics Alerts \| Rewards Program \| Surveys \| System Alerts \| Voting Reminders \| Waitlist Alerts \| Webinar Reminders \| Workshop Alerts
`use_case_summary`required	string
`sample_messages`required	string[]
`opt_in_workflow`required	string
`opt_in_image_urls`required	string[]
`opt_in_confirmation_message`required	string
`help_message`required	string
`privacy_policy_url`required	string
`terms_url`required	string	Can be null
`monthly_volume`required	string	One of: 10 \| 100 \| 1,000 \| 10,000 \| 100,000 \| 250,000 \| 500,000 \| 750,000 \| 1,000,000 \| 5,000,000 \| 10,000,000+
`age_gated`required	boolean
`additional_information`required	string	Can be null
`fee_cents`required	integer	The verification fee for this application, in cents CAD.
`payment_url`required	string	While AWAITING_PAYMENT: the dashboard page where the fee is paid. Null otherwise. Can be null
`paid_at`required	string	Format: date-time Can be null
`refunded_at`required	string	Format: date-time Can be null
`reviewer_note`required	string	What HonkIO staff asked to change, or why they declined the application. Can be null
`carrier_status`required	string	Where the carrier's review stands once it has the application: pending, action_needed (the carrier asked HonkIO a question; nothing for you to do yet), approved or rejected. Null before it is submitted. One of: pending \| action_needed \| approved \| rejected Can be null
`carrier_rejection_reason`required	string	Why the carrier rejected the application, when it did. Can be null
`submitted_at`required	string	Format: date-time Can be null
`decided_at`required	string	When the carrier approved or rejected it. Format: date-time Can be null
`created_at`required	string	Format: date-time
`updated_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.
409NUMBER_IN_OPEN_VERIFICATION: a number is already on another open application (details.phone_number_id).The standard error body.
422VALIDATION_ERROR (details names the fields), NOT_A_TOLL_FREE_NUMBER (a number is not one of your toll-free numbers; details.phone_number_id), or LIVE_MODE_REQUIRED for a test key.The standard error body.
429RATE_LIMITED: 10 new applications per day per account.The standard error body.
500Unexpected server error.The standard error body.

Example

const { data: application, error } = await honkio.tollFreeVerifications.create({
  phoneNumberIds: ['NUMBER_ID'], // your toll-free numbers, 1 to 5
  application: {
    businessName: 'Acme Clinics Inc.',
    entityType: 'PRIVATE_PROFIT',
    businessRegistrationNumber: '123456789RC0001',
    businessAddress: { line1: '100 King St W', city: 'Toronto', province: 'ON', postalCode: 'M5X 1A9' },
    contact: { firstName: 'Ada', lastName: 'Lovelace', email: 'ada@acme.ca', phone: '+1416XXXXXXX' },
    website: 'https://acme.ca',
    useCase: 'Appointments',
    useCaseSummary: 'Appointment reminders for our patients.',
    sampleMessages: ['Acme Clinics: your appointment is tomorrow at 2 pm. Reply STOP to opt out.'],
    optInWorkflow: 'Patients tick an unchecked SMS box on the booking form.',
    optInImageUrls: ['https://acme.ca/img/booking-form-sms-box.png'],
    optInConfirmationMessage: 'Acme Clinics: you are subscribed to appointment texts. Reply STOP to opt out.',
    helpMessage: 'Acme Clinics: visit acme.ca/help. Reply STOP to opt out.',
    privacyPolicyUrl: 'https://acme.ca/privacy',
    monthlyVolume: '10,000',
  },
})
if (error) throw new Error(`${error.name}: ${error.message}`)
console.log(application.id, application.status) // 'DRAFT'

curl -X POST https://api.honkio.ca/v1/toll-free-verifications \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_ids": [
      "+1613XXXXXXX"
    ],
    "application": {
      "business_name": "...",
      "entity_type": "SOLE_PROPRIETOR",
      "business_registration_number": "+1613XXXXXXX",
      "business_address": {
        "line1": "...",
        "city": "...",
        "province": "AB",
        "postal_code": "..."
      },
      "contact": {
        "first_name": "...",
        "last_name": "...",
        "email": "sam@example.com",
        "phone": "+1613XXXXXXX"
      },
      "website": "...",
      "use_case": "2FA",
      "use_case_summary": "...",
      "sample_messages": [
        "..."
      ],
      "opt_in_workflow": "...",
      "opt_in_image_urls": [
        "..."
      ],
      "opt_in_confirmation_message": "...",
      "help_message": "...",
      "privacy_policy_url": "https://example.com/webhooks/honkio",
      "monthly_volume": "10"
    }
  }'

get/v1/toll-free-verifications/{id}

Get a toll-free verification application

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

The application, its numbers, its status and, when staff asked for changes or declined it, their note.

Requires phone_numbers:r.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

200The application.

Field	Type	Description
`id`required	string
`status`required	string	DRAFT, then AWAITING_PAYMENT, IN_REVIEW (HonkIO staff), SUBMITTED (with the carrier) and APPROVED. CHANGES_REQUESTED and REJECTED (by the carrier) can be edited and submitted again, and a REJECTED one can be withdrawn (CANCELLED); DECLINED (by HonkIO) and CANCELLED are final. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED \| CANCELLED
`phone_numbers[]`required	object[]
`id`required	string
`phone_number`required	string
`application`required	object	The application as stored: every field, with the business number, postal code and phone normalized.
`business_name`required	string
`doing_business_as`required	string	Can be null
`entity_type`required	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string
`business_address`required	object
`line1`required	string
`city`required	string
`province`required	string
`postal_code`required	string
`contact`required	object
`first_name`required	string
`last_name`required	string
`email`required	string
`phone`required	string
`website`required	string
`use_case`required	string	One of: 2FA \| App Notifications \| Appointments \| Auctions \| Auto Repair Services \| Bank Transfers \| Billing \| Booking Confirmations \| Business Updates \| COVID-19 Alerts \| Career Training \| Chatbot \| Conversational / Alerts \| Courier Services & Deliveries \| Emergency Alerts \| Events & Planning \| Financial Services \| Fraud Alerts \| Fundraising \| General Marketing \| General School Updates \| HR / Staffing \| Healthcare Alerts \| Housing Community Updates \| Insurance Services \| Job Dispatch \| Legal Services \| Mixed \| Motivational Reminders \| Notary Notifications \| Order Notifications \| Political \| Public Works \| Real Estate Services \| Religious Services \| Repair and Diagnostics Alerts \| Rewards Program \| Surveys \| System Alerts \| Voting Reminders \| Waitlist Alerts \| Webinar Reminders \| Workshop Alerts
`use_case_summary`required	string
`sample_messages`required	string[]
`opt_in_workflow`required	string
`opt_in_image_urls`required	string[]
`opt_in_confirmation_message`required	string
`help_message`required	string
`privacy_policy_url`required	string
`terms_url`required	string	Can be null
`monthly_volume`required	string	One of: 10 \| 100 \| 1,000 \| 10,000 \| 100,000 \| 250,000 \| 500,000 \| 750,000 \| 1,000,000 \| 5,000,000 \| 10,000,000+
`age_gated`required	boolean
`additional_information`required	string	Can be null
`fee_cents`required	integer	The verification fee for this application, in cents CAD.
`payment_url`required	string	While AWAITING_PAYMENT: the dashboard page where the fee is paid. Null otherwise. Can be null
`paid_at`required	string	Format: date-time Can be null
`refunded_at`required	string	Format: date-time Can be null
`reviewer_note`required	string	What HonkIO staff asked to change, or why they declined the application. Can be null
`carrier_status`required	string	Where the carrier's review stands once it has the application: pending, action_needed (the carrier asked HonkIO a question; nothing for you to do yet), approved or rejected. Null before it is submitted. One of: pending \| action_needed \| approved \| rejected Can be null
`carrier_rejection_reason`required	string	Why the carrier rejected the application, when it did. Can be null
`submitted_at`required	string	Format: date-time Can be null
`decided_at`required	string	When the carrier approved or rejected it. Format: date-time Can be null
`created_at`required	string	Format: date-time
`updated_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.
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.tollFreeVerifications.get('VERIFICATION_ID')
if (error) throw new Error(error.message)
console.log(data.status, data.reviewer_note, data.carrier_rejection_reason)

curl https://api.honkio.ca/v1/toll-free-verifications/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

patch/v1/toll-free-verifications/{id}

Update a toll-free verification application

Permissionphone_numbers:mNode.js SDKhonkio.tollFreeVerifications.update()

Edits an application in DRAFT, CHANGES_REQUESTED or REJECTED. Its status does not change: submit it again when you are done. Live keys only.

Requires phone_numbers:m.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Request body

The fields to change. Application fields you send replace the stored ones (an address or contact is replaced whole); the result must still be a complete, valid application.

Field	Type	Description
`phone_number_ids`	string[]	Replaces the numbers on the application: 1 to 5 of your toll-free numbers.
`application`	object	Any of the application's fields.
`business_name`	string	At least 1 characters At most 255 characters
`doing_business_as`	string	At most 255 characters Can be null
`entity_type`	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`	string	At most 40 characters
`business_registration_type`	string	One of: CRA
`business_registration_country`	string	One of: CA
`business_address`	object
`line1`required	string	At least 1 characters At most 255 characters
`city`required	string	At least 1 characters At most 100 characters
`province`required	string	One of: AB \| BC \| MB \| NB \| NL \| NS \| NT \| NU \| ON \| PE \| QC \| SK \| YT
`postal_code`required	string	At most 10 characters
`contact`	object
`first_name`required	string	At least 1 characters At most 100 characters
`last_name`required	string	At least 1 characters At most 100 characters
`email`required	string	Format: email At most 254 characters
`phone`required	string	At most 32 characters
`website`	string	At most 2048 characters
`use_case`	string	One of: 2FA \| App Notifications \| Appointments \| Auctions \| Auto Repair Services \| Bank Transfers \| Billing \| Booking Confirmations \| Business Updates \| COVID-19 Alerts \| Career Training \| Chatbot \| Conversational / Alerts \| Courier Services & Deliveries \| Emergency Alerts \| Events & Planning \| Financial Services \| Fraud Alerts \| Fundraising \| General Marketing \| General School Updates \| HR / Staffing \| Healthcare Alerts \| Housing Community Updates \| Insurance Services \| Job Dispatch \| Legal Services \| Mixed \| Motivational Reminders \| Notary Notifications \| Order Notifications \| Political \| Public Works \| Real Estate Services \| Religious Services \| Repair and Diagnostics Alerts \| Rewards Program \| Surveys \| System Alerts \| Voting Reminders \| Waitlist Alerts \| Webinar Reminders \| Workshop Alerts
`use_case_summary`	string	At least 10 characters At most 2000 characters
`sample_messages`	string[]
`opt_in_workflow`	string	At least 10 characters At most 2000 characters
`opt_in_image_urls`	string[]
`opt_in_confirmation_message`	string	At least 1 characters At most 1000 characters
`help_message`	string	At least 1 characters At most 1000 characters
`privacy_policy_url`	string	At most 2048 characters
`terms_url`	string	At most 2048 characters Can be null
`monthly_volume`	string	One of: 10 \| 100 \| 1,000 \| 10,000 \| 100,000 \| 250,000 \| 500,000 \| 750,000 \| 1,000,000 \| 5,000,000 \| 10,000,000+
`age_gated`	boolean
`additional_information`	string	At most 2000 characters Can be null

Responses

200The edited application.

Field	Type	Description
`id`required	string
`status`required	string	DRAFT, then AWAITING_PAYMENT, IN_REVIEW (HonkIO staff), SUBMITTED (with the carrier) and APPROVED. CHANGES_REQUESTED and REJECTED (by the carrier) can be edited and submitted again, and a REJECTED one can be withdrawn (CANCELLED); DECLINED (by HonkIO) and CANCELLED are final. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED \| CANCELLED
`phone_numbers[]`required	object[]
`id`required	string
`phone_number`required	string
`application`required	object	The application as stored: every field, with the business number, postal code and phone normalized.
`business_name`required	string
`doing_business_as`required	string	Can be null
`entity_type`required	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string
`business_address`required	object
`line1`required	string
`city`required	string
`province`required	string
`postal_code`required	string
`contact`required	object
`first_name`required	string
`last_name`required	string
`email`required	string
`phone`required	string
`website`required	string
`use_case`required	string	One of: 2FA \| App Notifications \| Appointments \| Auctions \| Auto Repair Services \| Bank Transfers \| Billing \| Booking Confirmations \| Business Updates \| COVID-19 Alerts \| Career Training \| Chatbot \| Conversational / Alerts \| Courier Services & Deliveries \| Emergency Alerts \| Events & Planning \| Financial Services \| Fraud Alerts \| Fundraising \| General Marketing \| General School Updates \| HR / Staffing \| Healthcare Alerts \| Housing Community Updates \| Insurance Services \| Job Dispatch \| Legal Services \| Mixed \| Motivational Reminders \| Notary Notifications \| Order Notifications \| Political \| Public Works \| Real Estate Services \| Religious Services \| Repair and Diagnostics Alerts \| Rewards Program \| Surveys \| System Alerts \| Voting Reminders \| Waitlist Alerts \| Webinar Reminders \| Workshop Alerts
`use_case_summary`required	string
`sample_messages`required	string[]
`opt_in_workflow`required	string
`opt_in_image_urls`required	string[]
`opt_in_confirmation_message`required	string
`help_message`required	string
`privacy_policy_url`required	string
`terms_url`required	string	Can be null
`monthly_volume`required	string	One of: 10 \| 100 \| 1,000 \| 10,000 \| 100,000 \| 250,000 \| 500,000 \| 750,000 \| 1,000,000 \| 5,000,000 \| 10,000,000+
`age_gated`required	boolean
`additional_information`required	string	Can be null
`fee_cents`required	integer	The verification fee for this application, in cents CAD.
`payment_url`required	string	While AWAITING_PAYMENT: the dashboard page where the fee is paid. Null otherwise. Can be null
`paid_at`required	string	Format: date-time Can be null
`refunded_at`required	string	Format: date-time Can be null
`reviewer_note`required	string	What HonkIO staff asked to change, or why they declined the application. Can be null
`carrier_status`required	string	Where the carrier's review stands once it has the application: pending, action_needed (the carrier asked HonkIO a question; nothing for you to do yet), approved or rejected. Null before it is submitted. One of: pending \| action_needed \| approved \| rejected Can be null
`carrier_rejection_reason`required	string	Why the carrier rejected the application, when it did. Can be null
`submitted_at`required	string	Format: date-time Can be null
`decided_at`required	string	When the carrier approved or rejected it. Format: date-time Can be null
`created_at`required	string	Format: date-time
`updated_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.
404NOT_FOUND: no such resource on this account.The standard error body.
409VERIFICATION_NOT_EDITABLE (not in DRAFT, CHANGES_REQUESTED or REJECTED) or NUMBER_IN_OPEN_VERIFICATION.The standard error body.
422VALIDATION_ERROR, NOT_A_TOLL_FREE_NUMBER, or LIVE_MODE_REQUIRED for a test key.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 { error } = await honkio.tollFreeVerifications.update('VERIFICATION_ID', {
  application: { optInImageUrls: ['https://acme.ca/img/booking-form-v2.png'] },
})
if (error) throw new Error(error.message)

curl -X PATCH https://api.honkio.ca/v1/toll-free-verifications/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application": {
      "opt_in_image_urls": [
        "https://acme.ca/img/booking-form-v2.png"
      ]
    }
  }'

delete/v1/toll-free-verifications/{id}

Cancel or withdraw a toll-free verification application

Permissionphone_numbers:dNode.js SDKhonkio.tollFreeVerifications.cancel()

Cancels an application in DRAFT or AWAITING_PAYMENT, or withdraws one the carrier REJECTED, and frees its numbers for another application. A withdrawn application's fee is not refunded; an application in review or with the carrier cannot be cancelled. Once the payment page has been opened, cancel from the dashboard instead (VERIFICATION_NOT_EDITABLE, reason checkout_started), so the open payment can be closed first. Live keys only.

Requires phone_numbers:d.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

204Cancelled.
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.
409VERIFICATION_NOT_EDITABLE: only DRAFT and AWAITING_PAYMENT applications can be cancelled.The standard error body.
422LIVE_MODE_REQUIRED for a test key.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 { error } = await honkio.tollFreeVerifications.cancel('VERIFICATION_ID')
if (error) throw new Error(error.message)

curl -X DELETE https://api.honkio.ca/v1/toll-free-verifications/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/toll-free-verifications/{id}/submit

Submit a toll-free verification application

Permissionphone_numbers:wNode.js SDKhonkio.tollFreeVerifications.submit()

From DRAFT: moves the application to AWAITING_PAYMENT and returns payment_url, the dashboard page where the verification fee is paid; once paid it goes to HonkIO staff for review. From CHANGES_REQUESTED or REJECTED: sends the edited application back for review, at no charge. Live keys only (LIVE_MODE_REQUIRED). Needs a verified business with a CRA business number on its profile (BUSINESS_VERIFICATION_REQUIRED, or BUSINESS_NUMBER_REQUIRED when the business as HonkIO verified it has none; see verified_details on /v1/business-verification).

Requires phone_numbers:w.

Parameters

Parameter	Type	Description
`id`requiredpath	string

Responses

200The application, AWAITING_PAYMENT with payment_url, or back IN_REVIEW.

Field	Type	Description
`id`required	string
`status`required	string	DRAFT, then AWAITING_PAYMENT, IN_REVIEW (HonkIO staff), SUBMITTED (with the carrier) and APPROVED. CHANGES_REQUESTED and REJECTED (by the carrier) can be edited and submitted again, and a REJECTED one can be withdrawn (CANCELLED); DECLINED (by HonkIO) and CANCELLED are final. One of: DRAFT \| AWAITING_PAYMENT \| IN_REVIEW \| CHANGES_REQUESTED \| SUBMITTED \| APPROVED \| REJECTED \| DECLINED \| CANCELLED
`phone_numbers[]`required	object[]
`id`required	string
`phone_number`required	string
`application`required	object	The application as stored: every field, with the business number, postal code and phone normalized.
`business_name`required	string
`doing_business_as`required	string	Can be null
`entity_type`required	string	One of: SOLE_PROPRIETOR \| PRIVATE_PROFIT \| PUBLIC_PROFIT \| NON_PROFIT \| GOVERNMENT
`business_registration_number`required	string
`business_address`required	object
`line1`required	string
`city`required	string
`province`required	string
`postal_code`required	string
`contact`required	object
`first_name`required	string
`last_name`required	string
`email`required	string
`phone`required	string
`website`required	string
`use_case`required	string	One of: 2FA \| App Notifications \| Appointments \| Auctions \| Auto Repair Services \| Bank Transfers \| Billing \| Booking Confirmations \| Business Updates \| COVID-19 Alerts \| Career Training \| Chatbot \| Conversational / Alerts \| Courier Services & Deliveries \| Emergency Alerts \| Events & Planning \| Financial Services \| Fraud Alerts \| Fundraising \| General Marketing \| General School Updates \| HR / Staffing \| Healthcare Alerts \| Housing Community Updates \| Insurance Services \| Job Dispatch \| Legal Services \| Mixed \| Motivational Reminders \| Notary Notifications \| Order Notifications \| Political \| Public Works \| Real Estate Services \| Religious Services \| Repair and Diagnostics Alerts \| Rewards Program \| Surveys \| System Alerts \| Voting Reminders \| Waitlist Alerts \| Webinar Reminders \| Workshop Alerts
`use_case_summary`required	string
`sample_messages`required	string[]
`opt_in_workflow`required	string
`opt_in_image_urls`required	string[]
`opt_in_confirmation_message`required	string
`help_message`required	string
`privacy_policy_url`required	string
`terms_url`required	string	Can be null
`monthly_volume`required	string	One of: 10 \| 100 \| 1,000 \| 10,000 \| 100,000 \| 250,000 \| 500,000 \| 750,000 \| 1,000,000 \| 5,000,000 \| 10,000,000+
`age_gated`required	boolean
`additional_information`required	string	Can be null
`fee_cents`required	integer	The verification fee for this application, in cents CAD.
`payment_url`required	string	While AWAITING_PAYMENT: the dashboard page where the fee is paid. Null otherwise. Can be null
`paid_at`required	string	Format: date-time Can be null
`refunded_at`required	string	Format: date-time Can be null
`reviewer_note`required	string	What HonkIO staff asked to change, or why they declined the application. Can be null
`carrier_status`required	string	Where the carrier's review stands once it has the application: pending, action_needed (the carrier asked HonkIO a question; nothing for you to do yet), approved or rejected. Null before it is submitted. One of: pending \| action_needed \| approved \| rejected Can be null
`carrier_rejection_reason`required	string	Why the carrier rejected the application, when it did. Can be null
`submitted_at`required	string	Format: date-time Can be null
`decided_at`required	string	When the carrier approved or rejected it. Format: date-time Can be null
`created_at`required	string	Format: date-time
`updated_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.
403BUSINESS_VERIFICATION_REQUIRED (verify your business first) or BUSINESS_NUMBER_REQUIRED (your verified business profile has no CRA business number, which toll-free verification needs).The standard error body.
404NOT_FOUND: no such resource on this account.The standard error body.
409VERIFICATION_NOT_EDITABLE: only DRAFT, CHANGES_REQUESTED and REJECTED applications can be submitted. COMPED_TOLL_FREE: toll-free numbers are not available on this account.The standard error body.
422LIVE_MODE_REQUIRED for a test key, or NOT_A_TOLL_FREE_NUMBER when a number was released since.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.tollFreeVerifications.submit('VERIFICATION_ID')
if (error) throw new Error(error.message)
console.log(data.status, data.payment_url) // a draft: 'AWAITING_PAYMENT' and where to pay the fee

curl -X POST https://api.honkio.ca/v1/toll-free-verifications/ID/submit \
  -H "Authorization: Bearer mk_live_YOUR_KEY"