Overview

A toll-free number can be used to send messages in US & Canada once it passes an additional verification process. Users who don’t verify their toll-free numbers will be blocked from sending messages as of November 8, 2023.

A verified toll-free number ensures that the business owning the number is identified, and that the message's content has been reviewed and does not oppose the Disallowed Content Policy. This process ensures better deliverability and less filtration.

To set up a new channel to send SMS messages using a toll-free number the following steps are required.

API Access

The following API requests can only be made using a valid access key, and attached to an access role, with an access policy that at least specifies the permissions to the resources outlined in each section below. Learn more about .

Find an available number

If you do not already have a US or Canadian toll-free number available in your workspace you can find one to purchase.

Purchase a number

Once you have found an available number you can purchase this by providing the numberStockItemIds matching the id your previous call returned

A successful request to this endpoint will start a recurring monthly subscription based on the monthly cost of the number.

Submit a verification application for a toll-free number(s)

Before you can use a toll-free number to send SMS messages, you must submit a toll-free number verification request and wait for it to be approved.

To make this call, you must provide following parameters:

UseCase categories must only be of these types

Message Volume can only be of this type:

Fields below are not required for the submission:

Responses

201: Created

422: Unprocessable Entity (Invalid verification submission)

400: Bad request

Fetch the status of a toll-free number verification

Once you submit your verification request, you must wait for it to be reviewed. You will be informed about the status of your submission in the portal, but you can also use the API to fetch your verification request status.

Statuses

Responses

200 OK:

404 Not Found:

Verification status Message

If verification is rejected, some information will be provided in the DeclineReasonDescription if is in Progress, and any additional details have been required by the reviewing authority, you can find details in the Message field

Update toll-free number verification submission

You can update verification submission with new information in two cases:

1. Authority has requested to add additional information. Your input is required.

1. Provide more accurate verification information without request of an authority.

Responses

200 OK:

404 Not Found:

422: Unprocessable Entity

Retrieve all Verification of a Workspaces