---
title: "Create a toll-free verification application"
method: POST
path: "/v1/toll-free-verifications"
tags: ["Phone Numbers"]
---

# Create a toll-free verification application

`POST /v1/toll-free-verifications`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/toll-free-verifications`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

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

- object: The numbers to verify and the application for them.
  - `phone_number_ids` string[], required: 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` object, required: The application. Every field is checked when you create it.
    - `business_name` string, required: The legal name of the business, as registered with the Canada Revenue Agency.
    - `doing_business_as` string, nullable: The name the business trades under, when it differs from the legal name.
    - `entity_type` 'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT', required: The kind of organization. GET /v1/toll-free-verifications/options lists the values with labels.
    - `business_registration_number` string, required: The CRA business number: 9 digits, optionally followed by a program account such as RC0001. Spaces and hyphens are ignored.
    - `business_registration_type` 'CRA': Optional. Always CRA: only Canadian businesses can apply.
    - `business_registration_country` 'CA': Optional. Always CA.
    - `business_address` object, required: The registered address of the business, in Canada.
      - `line1` string, required
      - `city` string, required
      - `province` 'AB' | 'BC' | 'MB' | 'NB' | 'NL' | 'NS' | 'NT' | 'NU' | 'ON' | 'PE' | 'QC' | 'SK' | 'YT', required: Two-letter province or territory code.
      - `postal_code` string, required: Canadian postal code, e.g. K1A 0B1.
    - `contact` object, required: The person the carrier and HonkIO staff can contact about this application.
      - `first_name` string, required
      - `last_name` string, required
      - `email` string, email, required
      - `phone` string, required: A North American phone number, e.g. +14165550100.
    - `website` string, required: The business website (https). Reviewers check that it matches the business.
    - `use_case` '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', required: What the messages are for. GET /v1/toll-free-verifications/options lists the values with labels.
    - `use_case_summary` string, required: A few sentences on what you send, to whom, and why they expect it.
    - `sample_messages` string[], required: 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` string, required: How recipients agree to receive your messages: where, how, and what they are told.
    - `opt_in_image_urls` string[], required: 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` string, required: The message a recipient gets right after opting in.
    - `help_message` string, required: The reply to HELP: who you are and how to reach you.
    - `privacy_policy_url` string, required: Your privacy policy (https).
    - `terms_url` string, nullable: Your terms of service (https), if you have them.
    - `monthly_volume` '10' | '100' | '1,000' | '10,000' | '100,000' | '250,000' | '500,000' | '750,000' | '1,000,000' | '5,000,000' | '10,000,000+', required: The number of messages you expect to send a month. GET /v1/toll-free-verifications/options lists the values with labels.
    - `age_gated` boolean: True when the messages are about age-restricted products such as alcohol or cannabis.
    - `additional_information` string, nullable: Anything else the reviewers should know.

## Response `201`

The application, in DRAFT.

- TollFreeVerification: A toll-free verification application: the numbers it covers, the business behind them and where it stands.
  - `id` string, required
  - `status` 'DRAFT' | 'AWAITING_PAYMENT' | 'IN_REVIEW' | 'CHANGES_REQUESTED' | 'SUBMITTED' | 'APPROVED' | 'REJECTED' | 'DECLINED' | 'CANCELLED', required: 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.
  - `phone_numbers` object[], required
    - `id` string, required
    - `phone_number` string, required
  - `application` object, required: The application as stored: every field, with the business number, postal code and phone normalized.
    - `business_name` string, required
    - `doing_business_as` string, nullable, required
    - `entity_type` 'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT', required
    - `business_registration_number` string, required
    - `business_address` object, required
      - `line1` string, required
      - `city` string, required
      - `province` string, required
      - `postal_code` string, required
    - `contact` object, required
      - `first_name` string, required
      - `last_name` string, required
      - `email` string, required
      - `phone` string, required
    - `website` string, required
    - `use_case` '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', required
    - `use_case_summary` string, required
    - `sample_messages` string[], required
    - `opt_in_workflow` string, required
    - `opt_in_image_urls` string[], required
    - `opt_in_confirmation_message` string, required
    - `help_message` string, required
    - `privacy_policy_url` string, required
    - `terms_url` string, nullable, required
    - `monthly_volume` '10' | '100' | '1,000' | '10,000' | '100,000' | '250,000' | '500,000' | '750,000' | '1,000,000' | '5,000,000' | '10,000,000+', required
    - `age_gated` boolean, required
    - `additional_information` string, nullable, required
  - `fee_cents` integer, required: The verification fee for this application, in cents CAD.
  - `payment_url` string, nullable, required: While AWAITING_PAYMENT: the dashboard page where the fee is paid. Null otherwise.
  - `paid_at` string, date-time, nullable, required
  - `refunded_at` string, date-time, nullable, required
  - `reviewer_note` string, nullable, required: What HonkIO staff asked to change, or why they declined the application.
  - `carrier_status` 'pending' | 'action_needed' | 'approved' | 'rejected' | 'null', nullable, required: 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.
  - `carrier_rejection_reason` string, nullable, required: Why the carrier rejected the application, when it did.
  - `submitted_at` string, date-time, nullable, required
  - `decided_at` string, date-time, nullable, required: When the carrier approved or rejected it.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: The API key lacks the permission this operation requires, or the account is suspended or closed.
- `409`: NUMBER_IN_OPEN_VERIFICATION: a number is already on another open application (details.phone_number_id).
- `422`: VALIDATION_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.
- `429`: RATE_LIMITED: 10 new applications per day per account.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)