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 API access.
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.
use the search parameter types=toll-free to only search for Toll Free Numbers
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)
To reduce the likelihood of rejection, ensure you are familiar with TFN registration examples and best practices. Specifically
Check this article for tips on how to write an effective useCaseSummary
Check this article on how to write an effective optInWorkflowDescription
Most TFN rejections are caused by unclear or incomplete useCaseSummary and/or optInWorkflowDescription
A-Sync : this will start a background process that may require some time to complete. A Get call may be required to to retrieve the final result .
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.
You can submit one toll-free number per verification request.
You are not allowed to submit the same number twice, unless the previous submission was resolved with status Rejected or Verified.
Once you submit your verification request, you have to wait for the submission 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
Statuses
Submitted
Verification is submitted and waiting to be reviewed
InProgress
Verification is being reviewed by authority. Additional information may be requested. In case of API integration please inspect the `statusMessage` object for more information.
Verified
Verification submission has been approved, and the number is ready to be used.
The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display. To know more, refer to the pagination section.
Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.
POST/workspaces/{workspaceId}/numbers-long-code
Authorization
Path parameters
workspaceId*WorkspaceId (string (uuid))
The ID for the workspace.
Example: "d386a801-ee8d-4aba-a7e4-78671bd3b11e"
Body
numberStockItemIds*array of string (uuid)
The unique identifiers of the numbers you want to buy. You can buy up to 25 numbers at a time.
This operation will incur wallet charges for the numbers. Before buying the number, you must reserve it.
