Toll-Free Numbers Verification API
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 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)
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 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
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.
To make this call, you must provide following parameters:
Parameter | Description |
---|---|
businessName | The name of the Business using Toll Free Number. |
businessAddr1 | The address of the Business using Toll Free Number. |
businessAddr2 (optional field) | The address of the Business using Toll Free Number. |
businessCity | The city of the Business using Toll Free Number. |
businessState | The state of the Business using Toll Free Number. |
businessZip | The zip/postal code of the Business using Toll Free Number. |
businessCountry | Country of the Business using Toll Free Number. |
corporateWebsite | The website of the Business using Toll Free Number. |
businessContactFirstName | Business contact first name. |
businessContactLastName | Business contact last name. |
businessContactEmail | Business contact email address. |
businessContactPhone | Business contact phone number. |
messageVolume | Estimate monthly volume of messages from the Toll Free Number. See more details below. |
phoneNumbers | IDs of Toll-Free numbers. |
useCase | The Category of the use case. See below types of UseCases |
useCaseSummary | Please provide a general idea of the use case and customer. |
productionMessageContent | Example of message content. |
optInWorkflowDescription | Description of the opt in workflow. |
optInWorkflowImageUrLs | Images showing the opt in workflow. |
additionalInformation (optional field) | Any additional information. |
isvReseller (optional field) | ISV Name. |
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
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.
|
Rejected | Verification submission has been rejected. |
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:
Authority has requested to add additional information. Your input is required.
Always check the ResubmissionAllow filed in the StatusMessage before using this method
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
A TFN may have multiple verifications (example the firs submission was rejected by the reviewing authority ) but only one of them can be active
Last updated