Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Toll-Free Verification API Onboarding Guide


(warning)

Warning

All Toll-Free numbers must be verified before they can be used for sms messaging in the United States and Canada. Starting Jan 31, 2024, a Twilio Toll-free number cannot send messages until the verification has been approved. Please see this support article(link takes you to an external page) for more information.


Overview

overview page anchor

With the Messaging Compliance API you can submit your North America Toll-Free phone number for verification, so that you're sending compliant messaging traffic through Twilio.

This onboarding guide describes the step-by-step walkthrough of the various API calls you will make to register for Toll-Free Verification capabilities using Twilio APIs.

This guide will cover:


The Toll-Free Verification process(link takes you to an external page) requires specific information to be submitted that will help to identify the end business and ensure that these businesses have the right measures in place to send compliant traffic.

Incomplete submissions can be rejected if the appropriate information is not supplied.

Please note that rejected submissions because of incorrect information can be edited via the Resubmit API or the Twilio Console (coming soon).

(information)

Info

If you are an ISV, see our support article for guidance on Toll-Free verification for ISVs(link takes you to an external page).

High Throughput for Toll-Free

high-throughput-for-toll-free page anchor

Toll-Free traffic verification is required for all North America Toll-Free phone numbers, including those needing high-throughput. High-Throughput Toll-Free SMS refers to increasing the MPS sending rate of your Toll-Free SMS number.

For details about how Twilio MPS and queueing works, see Toll-Free SMS and MMS messaging throughput (MPS)(link takes you to an external page).

Prerequisites for ISVs: create a TrustHub Primary Customer Profile for your Company

prerequisites-for-isvs-create-a-trusthub-primary-customer-profile-for-your-company page anchor
(warning)

Warning

Prior to submitting a Toll-Free Verification request with Twilio, you will need to create a TrustHub primary Customer Profile for your business. To do so, navigate to Account > TrustHub > Customer Profiles(link takes you to an external page) and click Create Primary Business Profile. For step-by-step guidance, see Create a Primary Customer Profile.

Before proceeding with Toll-Free verification for your customers as an ISV (Independent Software Vendor), your Primary Customer Profile must be in an APPROVED state. You can set up your customers with secondary profiles, if desired. Also note that the Primary Customer Profile needs to have ISV, Reseller or Partner value selected for Business Identity.

Please note that Primary Customer Profile and Primary Business Profile refer to the same resource in this context.

(information)

Info

Copy the Primary Customer Profile SID from your Profile Details (parent account) so it can be used in a later step. This will begin with BUXXXX.

Overview of the ISV architecture: Accounts, Subaccounts and TrustHub profiles

overview-of-the-isv-architecture-accounts-subaccounts-and-trusthub-profiles page anchor

TrustHub Customer profiles can be attached to a parent account or a subaccount, like shown in the graphic below.

Toll-Free verification supports both models, but the subaccout model is recommended, so that customers are separated. The Account SID used in the Messaging Compliance API is where the customer profile for the end business and Toll-Free verification record sits. The customer profile and toll-free phone number must be in the same account for toll-free verification.

TFV_ISV_CustomerProfiles-graphic.

2. Submit a Toll-Free Verification Request

2-submit-a-toll-free-verification-request page anchor
(warning)

Warning

Remember: if you are an ISV, before submitting a TFV request for your secondary customer(s) you must have a Primary Customer Profile for your own business, in an APPROVED state.

This step creates a verification record for an end-business's use of a U.S. Toll-Free phone number. Note: A U.S. Toll-Free number begins with one of the following three-digit codes: 800, 888, 877, 866, 855, 844 and 833.

POST:


_10
https://messaging.twilio.com/v1/Tollfree/Verifications

For ISVs, if you want to submit a verification request with a Customer Profile of your choice, see Option 2.2 A Customer Profile SID is provided. A Customer Profile for your end-business may have been created for use in other Twilio products, like A2P 10DLC messaging or voice trust products, and you can pull the business data already submitted to Twilio. The following option is for submitting a verification request without a Customer Profile SID:

Option 2.1: A Customer Profile SID is not provided

option-21-a-customer-profile-sid-is-not-provided page anchor

In this case, Twilio will create a business profile (BUXXXXX) for you during the verification submission. You will need to provide the required parameters below when making requests to this API endpoint.

Request Parameters:

ParameterField TypeValidationDescription
BusinessStreetAddress [required]StringNumber of characters <= 100The address of the business or organization using the Toll-Free phone number. For more information, see Business Address.
BusinessStreetAddress2 [optional]StringNumber of characters <= 100The second address of the business or organization using the Toll-Free phone number.
BusinessCity [required]StringNumber of characters <= 100The city of the business or organization using the Toll-Free phone number.
BusinessStateProvinceRegion [required]StringNumber of characters <= 100The state/province or region of the business or organization using the Toll-Free phone number.
BusinessPostalCode [required]StringNumber of characters <= 100The postal code of the business or organization using the Toll-Free phone number.
BusinessCountry [required]StringNumber of characters <= 2The ISO country code of the business or organization using the Toll-Free phone number.
BusinessContactFirstName [required]StringNumber of characters <= 500The first name of the contact for the business or organization using the Toll-Free phone number.
BusinessContactLastName [required]StringNumber of characters <= 500The last name of the contact for the business or organization using the Toll-Free phone number.
BusinessContactEmail [required]StringNumber of characters <= 500 The email format validation is: ^\\S+@\\S+\\.\\S+$ The validation restricts the value to start with a string + '@' + any string + '.' + end with a string (without spaces).The email address of the contact for the business or organization using the Toll-Free phone number.
BusinessContactPhone [required]StringValid E.164 format phone number.The phone number of the contact for the business or organization using the Toll-Free phone number.
BusinessName [required]StringNumber of characters <= 500The name of the business or organization using the Toll-Free phone number. For more information, see Business Name.
BusinessWebsite [required]StringNumber of characters <= 500The website of the business or organization using the Toll-Free phone number. For more information, see Business Website.
NotificationEmail [required]StringNumber of characters <= 500 The email format validation is: ^\\S+@\\S+\\.\\S+$The email address to receive the notification about the verification result.
UseCaseCategories [required]Array (String)One or more values: - TWO_FACTOR_AUTHENTICATION - ACCOUNT_NOTIFICATIONS - CUSTOMER_CARE - CHARITY_NONPROFIT - DELIVERY_NOTIFICATIONS - FRAUD_ALERT_MESSAGING - EVENTS - HIGHER_EDUCATION - K12 - MARKETING - POLLING_AND_VOTING_NON_POLITICAL - POLITICAL_ELECTION_CAMPAIGNS - PUBLIC_SERVICE_ANNOUNCEMENT - SECURITY_ALERTChoose the use case that you believe best fits your customer's traffic pattern. This should be the use case that best fits the types of messages being sent by this toll-free phone number.
UseCaseSummary [required]StringNumber of characters <= 500The explanation on how messaging is used by the business or organization. For more information, see Use Case Summary.
ProductionMessageSample [required]StringNumber of characters <= 1000An example of the message content, i.e., "This is Chris, I'm here with your order. Reply stop to opt-out". For more information, see Production Message Sample.
OptInImageUrls [required]Array (String)Number of characters <= 1000You must provide proof of consent to receive messaging collected from the consumer via this parameter, which can contain a link to the web form, a hosted image file, or a link to a document that tells the story of the opt-in. Multiple URLs are allowed. Any URL submitted must be reachable, resolvable and of access to the public. For more information, see Opt-In Image URLs.
OptInType [required]StringOne of the following exact values - VERBA - WEB_FOR - PAPER_FOR - VIA_TEX - MOBILE_QR_CODEDescribes how a user opts-in to text messages. For examples, see Opt-In Type. NOTE: The document or URL submitted in the OptInImageURL needs to demonstrate the OptInType chosen: -VERBAL, must include the sample verbal consent collection and examples in a document linked in the OptInImageURLs parameter -WEB_FORM, must include the link to the form in the OptInImageURLs parameter. -PAPER_FORM, must include a link to the form in the OptInImageURLs parameter. It can be a scanned image. -VIA_TEXT, must describe the keyword campaign in a document linked in the OptInImageURLs parameter. -MOBILE_QR_CODE, must include the QR Code in a document linked in the OptInImageURLs parameter -The sample submitted in the OptInImageURLs parameter should match the OptInType selection.
MessageVolume [required]StringOne of the following exact values - 1 - 10 - 1,00 - 10,00 - 100,00 - 250,00 - 500,00 - 750,00 - 1,000,00 - 5,000,00 - 10,000,000+The monthly volume estimation of messages from the Toll-Free Number. For more information, see Message Volume.
AdditionalInformation [optional]StringNumber of characters <= 500Additional info to help with the verification. For more information, see Additional Information.
TollfreePhoneNumberSid [required]StringValid phone number SID.The unique string that Twilio created to identify the toll-free phone number. For more information, see Toll-Free Phone Number SID.
ExternalReferenceId [optional]StringNumber of characters <= 50 It must be alphanumeric.Used to track submissions or phone numbers internally. This can be a ticket number from an internal ticketing system, database key, or any other identifier that you use to track a submission with.

Submit a Toll-Free Verification Request

submit-a-toll-free-verification-request page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_33
// Download the helper library from https://www.twilio.com/docs/node/install
_33
// Find your Account SID and Auth Token at twilio.com/console
_33
// and set the environment variables. See http://twil.io/secure
_33
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_33
const authToken = process.env.TWILIO_AUTH_TOKEN;
_33
const client = require('twilio')(accountSid, authToken);
_33
_33
client.messaging.v1.tollfreeVerifications
_33
.create({
_33
businessStreetAddress: '123 Main Street',
_33
businessStreetAddress2: 'Suite 101',
_33
businessCity: 'Anytown',
_33
businessStateProvinceRegion: 'AA',
_33
businessPostalCode: '11111',
_33
businessCountry: 'US',
_33
businessContactFirstName: 'firstname',
_33
businessContactLastName: 'lastname',
_33
businessContactEmail: 'email@company.com',
_33
businessContactPhone: '+1231231234',
_33
additionalInformation: 'see our privacy policy here www.johnscoffeeshop.com/privacypolicy',
_33
externalReferenceId: 'abc123xyz567',
_33
businessName: 'Owl, Inc.',
_33
businessWebsite: 'http://www.company.com',
_33
notificationEmail: 'support@company.com',
_33
useCaseCategories: ['TWO_FACTOR_AUTHENTICATION', 'MARKETING'],
_33
useCaseSummary: `This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop`,
_33
productionMessageSample: 'lorem ipsum',
_33
optInImageUrls: ['https://zipwhiptestbusiness.com/images/image1.jpg', 'https://zipwhiptestbusiness.com/images/image2.jpg'],
_33
optInType: 'VERBAL',
_33
messageVolume: '10',
_33
tollfreePhoneNumberSid: 'PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
_33
})
_33
.then(tollfree_verification => console.log(tollfree_verification.sid));

Output

_45
{
_45
"sid": "HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"regulated_item_sid": null,
_45
"customer_profile_sid": null,
_45
"trust_product_sid": null,
_45
"status": "PENDING_REVIEW",
_45
"date_created": "2021-01-27T14:18:35Z",
_45
"date_updated": "2021-01-27T14:18:36Z",
_45
"business_name": "Owl, Inc.",
_45
"business_street_address": "123 Main Street",
_45
"business_street_address2": "Suite 101",
_45
"business_city": "Anytown",
_45
"business_state_province_region": "AA",
_45
"business_postal_code": "11111",
_45
"business_country": "US",
_45
"business_website": "http://www.company.com",
_45
"business_contact_first_name": "firstname",
_45
"business_contact_last_name": "lastname",
_45
"business_contact_email": "email@company.com",
_45
"business_contact_phone": "+1231231234",
_45
"notification_email": "support@company.com",
_45
"use_case_categories": [
_45
"TWO_FACTOR_AUTHENTICATION",
_45
"MARKETING"
_45
],
_45
"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
_45
"production_message_sample": "lorem ipsum",
_45
"opt_in_image_urls": [
_45
"https://zipwhiptestbusiness.com/images/image1.jpg",
_45
"https://zipwhiptestbusiness.com/images/image2.jpg"
_45
],
_45
"opt_in_type": "VERBAL",
_45
"message_volume": "10",
_45
"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
_45
"tollfree_phone_number_sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"rejection_reason": null,
_45
"error_code": null,
_45
"edit_expiration": null,
_45
"edit_allowed": null,
_45
"rejection_reasons": null,
_45
"resource_links": {},
_45
"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"external_reference_id": "abc123xyz567"
_45
}

The customer_profile_sid will not be a part of the 201 Response as it's an asynchronous process. You will get a webhook and an email with the customer_profile_sid.

Response: (422 Unprocessable Entity)


_10
{
_10
"code": 422,
_10
"message": "Provided customer profile is not approved"
_10
}

Toll-Free Verification request parameters

toll-free-verification-request-parameters page anchor

This section provides a deeper description with examples of some of the above-mentioned request parameters.

Toll-Free phone number SID

toll-free-phone-number-sid page anchor

This is Twilio's phone number SID. Note that if a phone number moves accounts, the phone number SID changes and the toll-free verification no longer applies to the toll-free phone number. You will have to re-verify the phone number.

The end business the customer (end user) is engaging with. This should not be the ISV unless the ISV is:

  • the sole content creator,
  • sending messages on behalf of the ISV, or
  • content is branded with the ISV's name.

Approved Examples: John's Coffee Shop. The example includes the end business that will be sending out the SMS messages that the customer/mobile handset is engaging with.

Rejected Examples: Name of the ISV, N/A. If the end-user business information is not provided, it will be rejected as Toll-Free Verification requests must provide an end-user business information to be reviewed.

The website of the end business or the website the consumer is engaging with. This should be the website of the business name that was previously mentioned. If the business does not have a traditional website, it can include social media links (i.e., Facebook, Instagram, Twitter, etc.).

Approved Example: URL to direct end-user business.

Social media links are acceptable (i.e., Facebook, Instagram, Twitter), if the end business is a small with no direct webpage. The social media pages will need to be set to public, so they can be reviewed.

Rejected Example: The URL is not a live website. The URL is behind a login/password or the website has the address of the ISV/aggregator.

In any of the following cases, the business website won't be reviewable:

  • The URL hasn't gone live yet, or
  • The URL is in a private state that requires a login/password.

Please note that business URLs are important for marketing use cases.

The address of the end business the consumer is engaging with. This should be the end business' physical location.

Approved Examples: 123 Main St, Seattle, WA, 98119

Full business address includes: the street, city, state, and zip code for the end business that will be sending out the SMS that the customer/mobile handset is engaging with. This would be the physical location of the business or organization.

Rejected Examples: "N/A" or the address of the ISV

The business address of the ISV is not a valid address.

The estimated monthly volume on the toll-free phone number referenced in the submission. Choose the closest value and if it increases, use the value of where you expect to be in 6 months.

Select the use case that you believe best fits your customer's traffic pattern. This should be the use case that best fits the types of messages being sent by this toll-free phone number.

Production Message Sample

production-message-sample page anchor

Refers to the production level sample message(s) that the end-business will be sending to the end-user/mobile handset.

Approved Examples: "Thank you for being a loyal customer of John's Coffee Shop. Enjoy 10% off your next purchase. Reply STOP to opt out."

This should be a sample message of the content that the end-user/mobile handset will be receiving in the SMS.

Rejected Examples: "Your appointment is today at 10:00 AM".

The sample message content should match the use case provided i.e., Marketing.

The explanation on how messaging is used on this toll-free phone number by the business or organization. The more detailed information you provide for the use case/summary the better.

Approved Examples: This number is used to send out promotional offers and coupons to the customers of for example the John's Coffee Shop

Rejected Examples: Marketing

The rejected example message doesn't specify for what type of marketing the number is used for or what will the end-user/mobile handset be receiving from the end-user business.

Opt-in refers to the process of getting end-user permission to send them text messages. According to TCPA law, businesses must have "express written consent" from the end-user before texting them.

The OptInType and OptInImageUrls provided should outline the details of how an end-user provides consent when they provide their phone number to receive texts from the end business that is going to engage with them. The sample submitted in the OptInImageURLs parameter should match the OptInType selection. The document or URL submitted in the OptInImageURL needs to demonstrate the OptInType chosen.

The opt-in provided must be appropriate for the Use Case Category submitted. For example, a marketing campaign must collect express consent where the end-user handset positively affirms their enrollment in the campaign.

OptInTypeExamples:
VERBALTwilio IVR: "As part of our service, we can send you automated monthly text alerts regarding Twilio account payment activity. We will send two messages per month. Message and data rates may apply, depending on your mobile phone service plan. At any time you can get more help by replying HELP to these texts, or you can opt out completely by replying STOP. Mobile Terms of Service are available at "example.com/terms" and our Privacy Statement can be found at "example.com/privacy". Please reply with 'yes' or 'no' to indicate if you would like this service". Twilio Customer: "Yes please" Twilio IVR: "Great! We will send you a text message to confirm your enrollment here shortly." NOTE: If you choose VERBAL, you must provide the sample verbal consent collection in the OptInImageURLs document
WEB_FORMAn embedded form on the end-business's website that prompts end-users to enter their mobile handset phone number and opt into the texting campaign.
TFV_WebFormExample.
Build your own SMS Opt-In template here(link takes you to an external page) NOTE: If you choose WEB_FORM, you must provide the link to it in the OptInImageURLs parameter
PAPER_FORMAn in-store visitor completes a physical form that collects their phone number and their consent to subscribe to your texting campaign. NOTE: If you choose PAPER_FORM, you must provide the form in the OptInImageURLs document
VIA_TEXTA Keyword campaign example:
TFV_TextKeywordCampaign.
NOTE: If you choose VIA_TEXT, you must provide the keyword campaign info in the OptInImageURLs document
MOBILE_QR_CODEA QR code that links to an online form that prompts end-users to enter their mobile handset phone number and opt into the texting campaign. QR code can direct the mobile handset to their messaging application with a templated opt-in message, or can lead to a web-form as outlined above. NOTE: If you choose MOBILE_QR_CODE, you must provide the QR Code in the OptInImageURLs document.

Consent is one of the cornerstones of A2P messaging.You must demonstrate how consent to receive messaging is collected from the consumer. You must provide proof of consent collection via this OptInImageUrls parameter, which can contain a link to the web form, a hosted image file, or a link to a document that tells the story of the opt-in. Such as a screenshot of the opt-in clearly displayed on the end-user's website, an image of where opt-in is collected or an image of relevant opt-in practice, a document with the QR code, etc. Any URL submitted must be reachable, resolvable and of access to the public. Don't include links with opt-ins behind username/password logins, links to secured google drives, or other non-public accessible websites. You will need to host the image on your website or server and generate a link to it, which you can then provide in this field in the form.

The Opt-In workflow description in this document should briefly describe how the consumer gives consent to the business to receive messaging. In as much detail, provide how a consumer/subscriber opts into this submission and should be where the customer's phone number was entered by the customer agreeing to receive the SMS.. The opt-in submitted should be what the mobile user sees when they provide their phone number (thereby giving consent): online/app (URL, screenshot/webpage), see in store (keyword, signage), or hears (IVR script/verbiage). It should demonstrate the Opt-In Type selected.

The more detail about the opt in process, the better. The information provided for review, within the OptInImageUrls example, should be clear to the Verification Ops team what specifically the customer does to opt in/sign up to receive SMS from the end-user business.

  • VERBAL, must include the sample verbal consent collection (e.g. script) in a document.
  • WEB_FORM, provide the link to the direct opt-in page or you can include a screenshot of the website opt-in page. Note that only the phone number opt in page should be included. An opt-in for an email address is not acceptable for SMS toll-free verification opt in.
  • PAPER_FORM, provide the form. Can be a scanned copy.
  • VIA_TEXT, must describe the keyword campaign in a document. What is the keyword? Where does the consumer/subscriber find the keyword? Screenshots/pictures/urls are best.
  • MOBILE_QR_CODE, include a document with the QR Code.

EXAMPLES

Approved Example: http://www.johnscoffeeshop.com/signupforsms(link takes you to an external page)

This is a direct URL to the opt-in sign up page.

Approved Example:http://www.johnscoffeeshop.com/image123.png(link takes you to an external page)

This is a publicly accessible link to a hosted image of the opt-in or Screenshot of the SMS opt in page.

Approved Example:http://www.johnscoffeeshop.com/document123.docx(link takes you to an external page)

This is a publicly accessible link to a hosted document of the opt-in process.

Approved Example: a document that outlines - "Keyword: Coffee. The keyword is found on a sign at the register of John's Coffee Shop where customers can see the keyword and text in to the Toll-Free Number. Once the customer texts the keyword, they are provided a double opt in where they are asked to Reply Y to confirm they would like to receive promotional SMS"

This includes a good amount of detail about the opt-in process. It addresses what the keyword is, where the customer finds the keyword and what happens after the end-user/mobile handset texts the keyword to the Toll-Free number.

Rejected Example:http://www.johnscoffeeshop.com(link takes you to an external page)

URLs that don't direct to the exact sign-up, URLs that are behind a login/password screen or URLs that don't resolve.

Rejected Examples: a document that outlines a point of sale situation, but it vague on details, like: "Customer receives a text of a point of sale receipt"

It doesn't demonstrate the process. Where does the customer give the consent? Provide a screenshot/picture/url from the POS and language the customer is agreeing to.

Any additional details (i.e., privacy policies, onboarding controls, etc…) that you want to add or that you believe will help with the verification such as privacy policies, AUPs, additional onboarding controls you have, links, etc.

Approved Examples:http://www.johnscoffeeshop.com/privacypolicy(link takes you to an external page)

Option 2.2: A Customer Profile SID is provided

option-22-a-customer-profile-sid-is-provided page anchor

In this case, in addition to the CustomerProfileSid parameter, there are required parameters that you will need to pass when making requests to this API endpoint.

If you provide a Customer Profile and you encounter an error which states "unnecessary business information", please remove the following fields:

  • BusinessStreetAddress
  • BusinessStreetAddress2
  • BusinessCity
  • BusinessStateProvinceRegion
  • BusinessPostalCode
  • BusinessCountry
  • BusinessContactFirstName
  • BusinessContactLastName
  • BusinessContactEmail
  • BusinessContactPhone

Request Parameters:

ParameterField TypeValidationDescription
CustomerProfileSid [required]StringThe profile should be in an approved state. Valid provided profile types: ISV Starter Profile and SCP.It's the unique string created to identify the CustomerProfile resource (BUXXXXXX). To retrieve your customer profile SID, see Retrieve Customer Profile SID.
BusinessName [required]StringNumber of characters <= 500The name of the business or organization using the Toll-Free phone number. For more information, see Business Name.
BusinessWebsite [required]StringNumber of characters <= 500The website of the business or organization using the Toll-Free phone number. For more information, see Business Website.
NotificationEmail [required]StringNumber of characters <= 500 The email format validation: ^\\S+@\\S+\\.\\S+$The email address to receive the notification about the verification result. For ISVs, this would most likely be the ISV's email address.
MessageVolume [required]StringOne of the following exact values: - 10 - 100 - 1,000 - 10,000 - 100,000 - 250,000 - 500,000 - 750,000 - 1,000,000 - 5,000,000 - 10,000,000+The monthly volume of messages estimation from the Toll-Free phone number. For more information, see Message Volume
UseCaseCategories [required]Array (String)One or more values - TWO_FACTOR_AUTHENTICATIO - ACCOUNT_NOTIFICATION - CUSTOMER_CAR - CHARITY_NONPROFI - DELIVERY_NOTIFICATION - FRAUD_ALERT_MESSAGIN - EVENT - HIGHER_EDUCATIO - K1 - MARKETIN - POLLING_AND_VOTING_NON_POLITICA - POLITICAL_ELECTION_CAMPAIGN - PUBLIC_SERVICE_ANNOUNCEMEN - SECURITY_ALERTChoose the use case that you believe best fits your customer's traffic pattern. This should be the use case that best fits the types of messages being sent by this toll-free phone number.
UseCaseSummary [required]StringNumber of characters <= 500Explains how messaging is used by the business or organization. For more information, see Use Case Summary.
ProductionMessageSample [required]StringNumber of characters <= 1000It's an example of the message content, i.e. "This is Chris, I'm here with your order. Reply stop to opt-out". For more information, see Production Message Sample.
OptInImageUrls [required]Array (String)Number of characters <= 1000You must provide proof of consent to receive messaging collected from the consumer via this parameter, which can contain a link to the web form, a hosted image file, or a link to a document that tells the story of the opt-in. Multiple URLs are allowed. Any URL submitted must be reachable, resolvable and of access to the public. For more information, see Opt-In Image URLs.
OptInType [required]StringOne of the following exact values - VERBA - WEB_FOR - PAPER_FOR - VIA_TEX - MOBILE_QR_CODEDescribes how a user opts-in to text messages. For examples, see Opt-In Type. NOTE: The document or URL submitted in the OptInImageURL needs to demonstrate the OptInType chosen: -VERBAL, must include the sample verbal consent collection and examples in a document linked in the OptInImageURLs parameter -WEB_FORM, must include the link to the form in the OptInImageURLs parameter. -PAPER_FORM, must include a link to the form in the OptInImageURLs parameter. It can be a scanned image. -VIA_TEXT, must describe the keyword campaign in a document linked in the OptInImageURLs parameter. -MOBILE_QR_CODE, must include the QR Code in a document linked in the OptInImageURLs parameter -The sample submitted in the OptInImageURLs parameter should match the OptInType selection.
TollfreePhoneNumberSid [required]StringValid E.164 format phone number.The Toll-Free phone number in E.164 format that needs to get verified. This is the phone number SID. For more information, see Toll-Free Phone Number SID.
AdditionalInformation [optional]StringNumber of characters <= 500Additional documentation provided by the customer. For more information, see Additional Information.
ExternalReferenceId [optional]String50 chars Must be alphanumericUsed to track submissions or phone numbers internally. This can be a ticket number from an internal ticketing system, database key, or any other identifier that you use to track a submission with.

Submit a Toll-Free Verification Request Using Existing Customer Profile

submit-a-toll-free-verification-request-using-existing-customer-profile page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_24
// Download the helper library from https://www.twilio.com/docs/node/install
_24
// Find your Account SID and Auth Token at twilio.com/console
_24
// and set the environment variables. See http://twil.io/secure
_24
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_24
const authToken = process.env.TWILIO_AUTH_TOKEN;
_24
const client = require('twilio')(accountSid, authToken);
_24
_24
client.messaging.v1.tollfreeVerifications
_24
.create({
_24
customerProfileSid: 'BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
_24
additionalInformation: 'see our privacy policy here www.johnscoffeeshop.com/privacypolicy',
_24
externalReferenceId: 'abc123xyz567',
_24
businessName: 'Owl, Inc.',
_24
businessWebsite: 'http://www.company.com',
_24
notificationEmail: 'support@company.com',
_24
useCaseCategories: ['TWO_FACTOR_AUTHENTICATION', 'MARKETING'],
_24
useCaseSummary: `This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop`,
_24
productionMessageSample: 'lorem ipsum',
_24
optInImageUrls: ['https://zipwhiptestbusiness.com/images/image1.jpg', 'https://zipwhiptestbusiness.com/images/image2.jpg'],
_24
optInType: 'VERBAL',
_24
messageVolume: '10',
_24
tollfreePhoneNumberSid: 'PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
_24
})
_24
.then(tollfree_verification => console.log(tollfree_verification.sid));

Output

_45
{
_45
"sid": "HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"customer_profile_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"regulated_item_sid": null,
_45
"trust_product_sid": null,
_45
"business_name": "Owl, Inc.",
_45
"status": "PENDING_REVIEW",
_45
"date_created": "2021-01-27T14:18:35Z",
_45
"date_updated": "2021-01-27T14:18:36Z",
_45
"business_street_address": "123 Main Street",
_45
"business_street_address2": "Suite 101",
_45
"business_city": "Anytown",
_45
"business_state_province_region": "AA",
_45
"business_postal_code": "11111",
_45
"business_country": "US",
_45
"business_website": "http://www.company.com",
_45
"business_contact_first_name": "firstname",
_45
"business_contact_last_name": "lastname",
_45
"business_contact_email": "email@company.com",
_45
"business_contact_phone": "+11231231234",
_45
"notification_email": "support@company.com",
_45
"use_case_categories": [
_45
"TWO_FACTOR_AUTHENTICATION",
_45
"MARKETING"
_45
],
_45
"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
_45
"production_message_sample": "lorem ipsum",
_45
"opt_in_image_urls": [
_45
"https://zipwhiptestbusiness.com/images/image1.jpg",
_45
"https://zipwhiptestbusiness.com/images/image2.jpg"
_45
],
_45
"opt_in_type": "VERBAL",
_45
"message_volume": "10",
_45
"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
_45
"tollfree_phone_number_sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"rejection_reason": null,
_45
"error_code": null,
_45
"edit_expiration": null,
_45
"edit_allowed": null,
_45
"rejection_reasons": null,
_45
"resource_links": {},
_45
"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"external_reference_id": "abc123xyz567"
_45
}

Response: (400 Bad Request)


_10
{
_10
"code": 400,
_10
"message": "Missing mandatory fields for submitting a verification"
_10
}

Retrieve Customer Profile SID (optional)

retrieve-customer-profile-sid-optional page anchor

You can select an existing Customer Profile SID associated to your Twilio Account by making a request to the TrustHub API as following:

Request:


_10
curl -X GET 'https://trusthub.twilio.com/v1/CustomerProfiles?PageSize=2' \
_10
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response:


_37
{
_37
"sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"policy_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"friendly_name": "friendly_name",
_37
"status": "draft",
_37
"valid_until": null,
_37
"email": "email",
_37
"status_callback": "http://www.example.com",
_37
"date_created": "2019-07-30T22:29:24Z",
_37
"date_updated": "2019-07-31T01:09:00Z",
_37
"url":
_37
"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"links": { "customer_profiles_entity_assignments":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/EntityAssignments",
_37
"customer_profiles_evaluations":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Evaluations",
_37
"customer_profiles_channel_endpoint_assignment":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ChannelEndpointAssignments"
_37
}
_37
},
_37
{
_37
"sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"policy_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"friendly_name": "another_friendly_name",
_37
"status": "twilio-approved",
_37
"valid_until": null,
_37
"email": "another_email",
_37
"status_callback": "http://www.example.com",
_37
"date_created": "2019-07-28T12:33:04Z",
_37
"date_updated": "2019-07-29T10:59:19Z",
_37
"url":
_37
"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"links": {
_37
"customer_profiles_entity_assignments":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/EntityAssignments",
_37
"customer_profiles_evaluations":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Evaluations",
_37
"customer_profiles_channel_endpoint_assignment":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ChannelEndpointAssignments"
_37
}
_37
}


3. List Toll Free Verification Records (optional)

3-list-toll-free-verification-records-optional page anchor
(warning)

Warning

If a Toll-Free phone number is NOT on the list, then it means it's Restricted.

This step returns a list of Toll-Free verification records for the account SID authenticated into the API. It does not include sub-accounts.

(information)

Info

Note: If you have previously submitted a Toll-Free phone number for verification using the CSV submission process(link takes you to an external page), and it was approved, those records will be available as of Private Beta. Rejected and Pending verification requests are not imported.

GET (LIST):


_10
https://messaging.twilio.com/v1/Tollfree/Verifications

Request parameters:

Parameter: Status

Required:

No

Description:

It's the status of the Toll Free verification. The status can be:

  • PENDING_REVIEW
  • IN_REVIEW
  • TWILIO_APPROVED
  • TWILIO_REJECTED

Parameter: TollfreePhoneNumberSid

Required:

No

Description:

It's the SID of the Toll Free phone number. You can use it to find the Toll Free verification record (PNXXXXXX).

Parameter: PageSize

Required:

No

Description:

It's the number of verification returned in a request. The maximum value is 50.

List Toll Free Verification Records

list-toll-free-verification-records page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messaging.v1.tollfreeVerifications
_10
.list({limit: 20})
_10
.then(tollfreeVerifications => tollfreeVerifications.forEach(t => console.log(t.sid)));

Output

_62
{
_62
"meta": {
_62
"page": 0,
_62
"page_size": 50,
_62
"first_page_url": "https://messaging.twilio.com/v1/Tollfree/Verifications?Status=TWILIO_APPROVED&TollfreePhoneNumberSid=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0",
_62
"previous_page_url": "https://messaging.twilio.com/v1/Tollfree/Verifications?Status=TWILIO_APPROVED&TollfreePhoneNumberSid=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0",
_62
"next_page_url": "https://messaging.twilio.com/v1/Tollfree/Verifications?Status=TWILIO_APPROVED&TollfreePhoneNumberSid=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=1",
_62
"key": "verifications",
_62
"url": "https://messaging.twilio.com/v1/Tollfree/Verifications?Status=TWILIO_APPROVED&TollfreePhoneNumberSid=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&PageSize=50&Page=0"
_62
},
_62
"verifications": [
_62
{
_62
"sid": "HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"customer_profile_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"trust_product_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"regulated_item_sid": "RAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"date_created": "2021-01-27T14:18:35Z",
_62
"date_updated": "2021-01-27T14:18:36Z",
_62
"business_name": "Owl, Inc.",
_62
"business_street_address": "123 Main Street",
_62
"business_street_address2": "Suite 101",
_62
"business_city": "Anytown",
_62
"business_state_province_region": "AA",
_62
"business_postal_code": "11111",
_62
"business_country": "US",
_62
"business_website": "http://www.company.com",
_62
"business_contact_first_name": "firstname",
_62
"business_contact_last_name": "lastname",
_62
"business_contact_email": "email@company.com",
_62
"business_contact_phone": "+11231231234",
_62
"notification_email": "support@company.com",
_62
"use_case_categories": [
_62
"TWO_FACTOR_AUTHENTICATION",
_62
"MARKETING"
_62
],
_62
"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
_62
"production_message_sample": "lorem ipsum",
_62
"opt_in_image_urls": [
_62
"https://testbusiness.com/images/image1.jpg",
_62
"https://testbusiness.com/images/image2.jpg"
_62
],
_62
"opt_in_type": "VERBAL",
_62
"message_volume": "1,000",
_62
"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
_62
"tollfree_phone_number_sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"status": "TWILIO_APPROVED",
_62
"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"rejection_reason": null,
_62
"error_code": null,
_62
"edit_expiration": null,
_62
"edit_allowed": null,
_62
"rejection_reasons": null,
_62
"resource_links": {
_62
"customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_62
"channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ChannelEndpointAssignments/RAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_62
},
_62
"external_reference_id": "abc123xyz567"
_62
}
_62
]
_62
}

Request with optional Status parameter:


_10
curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?Status=IN_REVIEW' \
_10
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Request with optional TollfreePhoneNumberSid parameter:


_10
curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?TollfreePhoneNumberSid=PNXXXXXXXXX' \
_10
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Request with both optional parameters:


_10
curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?TollfreePhoneNumberSid=PNXXXXXX&Status=IN_REVIEW' \
_10
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN


4. Retrieve a single Toll-Free Verification Record (optional)

4-retrieve-a-single-toll-free-verification-record-optional page anchor

This step returns a single Toll Free verification record for an account that has been submitted to Twilio.

GET:


_10
https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXX

Request parameter:

ParameterRequiredDescription
TollfreeVerificationSIDYesThe SID of the Toll Free verification record (HHXXXXXXXXXX).

Retrieve a single Toll-Free Verification Record

retrieve-a-single-toll-free-verification-record page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messaging.v1.tollfreeVerifications('HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(tollfree_verification => console.log(tollfree_verification.businessName));

Output

_49
{
_49
"sid": "HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"customer_profile_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"trust_product_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"regulated_item_sid": "RAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"date_created": "2021-01-27T14:18:35Z",
_49
"date_updated": "2021-01-27T14:18:36Z",
_49
"business_name": "Owl, Inc.",
_49
"business_street_address": "123 Main Street",
_49
"business_street_address2": "Suite 101",
_49
"business_city": "Anytown",
_49
"business_state_province_region": "AA",
_49
"business_postal_code": "11111",
_49
"business_country": "US",
_49
"business_website": "http://www.company.com",
_49
"business_contact_first_name": "firstname",
_49
"business_contact_last_name": "lastname",
_49
"business_contact_email": "email@company.com",
_49
"business_contact_phone": "+11231231234",
_49
"notification_email": "support@company.com",
_49
"use_case_categories": [
_49
"TWO_FACTOR_AUTHENTICATION",
_49
"MARKETING"
_49
],
_49
"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
_49
"production_message_sample": "lorem ipsum",
_49
"opt_in_image_urls": [
_49
"https://testbusiness.com/images/image1.jpg",
_49
"https://testbusiness.com/images/image2.jpg"
_49
],
_49
"opt_in_type": "VERBAL",
_49
"message_volume": "2000",
_49
"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
_49
"tollfree_phone_number_sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"status": "TWILIO_APPROVED",
_49
"rejection_reason": null,
_49
"error_code": null,
_49
"edit_expiration": null,
_49
"edit_allowed": null,
_49
"rejection_reasons": null,
_49
"resource_links": {
_49
"customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ChannelEndpointAssignments/RAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_49
},
_49
"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_49
"external_reference_id": "abc123xyz567"
_49
}

Response of a Verification Rejected example:

Note the error_code and rejection_reason. Refer to the rejected verifications section for a full list of error codes.


_45
{
_45
"sid": "HHXXXXXXXX",
_45
"account_sid": "AACXXXXXXXX",
_45
"toll_free_phone_number_sid": "PNXXXXXXX",
_45
"date_created": "2023-02-02T18:45:17.051372437Z",
_45
"date_updated": "2023-02-02T18:45:20.03161371Z",
_45
"status": "TWILIO_REJECTED",
_45
"customer_profile_sid": "BUXXXXXXXX",
_45
"trust_product_sid": "BUXXXXXXXX",
_45
"regulated_item_sid": "RAXXXXXXXX",
_45
"business_name": "Owl Inc.",
_45
"business_street_address": "123 Main Street",
_45
"business_street_address2": "Apt1",
_45
"businesss_city": "Anytown",
_45
"business_state_province_region": "AA",
_45
"business_postal_code": "11111",
_45
"business_country": "US",
_45
"business_website": "http:www.company.com",
_45
"business_contact_first_name": "firstname",
_45
"business_contact_last_name": "lastname",
_45
"business_contact_email": "email@company.com",
_45
"business_contact_phone": "1231231234",
_45
"notification_email": "test@example.com",
_45
"use_case_categories": [
_45
"EVENTS",
_45
"CUSTOMER_CARE"
_45
],
_45
"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
_45
"production_message_sample": "lorem ipsum",
_45
"opt_in_image_urls": ["https://owlinctestbusiness.com/images/image1.jpg"],
_45
"opt_in_type": "MOBILE_QR_CODE",
_45
"message_volume": "100",
_45
"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
_45
"external_verification_request_id": "123-456",
_45
"rejection_reason": "Invalid Information - Cant Validate URL",
_45
"error_code": 30445,
_45
"edit_expiration": "2023-02-09T18:45:20.03161371Z",
_45
"edit_allowed": true,
_45
"resource_links": {
_45
"customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXX",
_45
"trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXX",
_45
"channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXX/ChannelEndpointAssignments/RAXXXXXXX"
_45
},
_45
"external_reference_id": null
_45
}


5. Edit a rejected Toll-Free Verification request

5-edit-a-rejected-toll-free-verification-request page anchor

If a Toll-Free Verification request has been Twilio-rejected, it may be possible to edit and then re-submit the toll-free verification depending on which error code was returned. See which Status Codes allow a toll-free verification to be edited and submitted again for review. See the impact of not re-submitting within 7 days. Only rejected toll-free verification can be edited, all other statuses do not allow an edit.

The request and response are the same as described for initial submission. The fields that can be submitted do not include SIDs, as these cannot be changed. If the verification is being re-submitted for a technical reason such as the website being fixed, the EditReason field can be used to describe what was done. For example, "website fixed". The following fields can be included in the resubmission and are all optional but at least one field must be present:

  • MessageVolume
  • OptInImageUrls
  • BusinessWebsite
  • ProductionMessageSample
  • UseCaseCategories
  • UseCaseSummary
  • OptInType
  • BusinessName
  • NotificationEmail
  • BusinessStreetAddress
  • BusinessCity
  • BusinessStateProvinceRegion
  • BusinessPostalCode
  • BusinessCountry
  • BusinessContactFirstName
  • BusinessContactLastName
  • BusinessContactEmail
  • BusinessContactPhone
  • AdditionalInformation
  • EditReason

Please note that the URL is different as it contains the Toll-Free Verification SID (HHHXXXXXXX). You can obtain the verification SID from the response of the initial Toll-Free Verification request or from using the GET method to list all the Toll-Free verification records.

Response: (400 Bad Request)


_10
{
_10
"code": 400,
_10
"message": "Cannot edit an approved submission HHXXXXXXXXXXXXXXX",
_10
"more_info": "https://www.twilio.com/docs/errors/400",
_10
"status": 400
_10
}

Resubmit a Toll-Free Verification Request

resubmit-a-toll-free-verification-request page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_31
// Download the helper library from https://www.twilio.com/docs/node/install
_31
// Find your Account SID and Auth Token at twilio.com/console
_31
// and set the environment variables. See http://twil.io/secure
_31
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_31
const authToken = process.env.TWILIO_AUTH_TOKEN;
_31
const client = require('twilio')(accountSid, authToken);
_31
_31
client.messaging.v1.tollfreeVerifications('HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_31
.update({
_31
businessName: 'Owl, Inc.',
_31
businessStreetAddress: '123 Main Street',
_31
businessStreetAddress2: 'Suite 101',
_31
businessCity: 'Anytown',
_31
businessStateProvinceRegion: 'AA',
_31
businessPostalCode: '11111',
_31
businessCountry: 'US',
_31
businessWebsite: 'http://www.company.com',
_31
businessContactFirstName: 'firstname',
_31
businessContactLastName: 'lastname',
_31
businessContactEmail: 'email@company.com',
_31
businessContactPhone: '+1231231234',
_31
notificationEmail: 'support@company.com',
_31
useCaseCategories: ['TWO_FACTOR_AUTHENTICATION', 'MARKETING'],
_31
useCaseSummary: `This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop`,
_31
productionMessageSample: 'lorem ipsum',
_31
optInImageUrls: ['https://zipwhiptestbusiness.com/images/image1.jpg', 'https://zipwhiptestbusiness.com/images/image2.jpg'],
_31
optInType: 'VERBAL',
_31
messageVolume: '1,000',
_31
additionalInformation: 'see our privacy policy here www.johnscoffeeshop.com/privacypolicy'
_31
})
_31
.then(tollfree_verification => console.log(tollfree_verification.businessName));

Output

_45
{
_45
"sid": "HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"regulated_item_sid": null,
_45
"customer_profile_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"trust_product_sid": null,
_45
"status": "PENDING_REVIEW",
_45
"date_created": "2021-01-27T14:18:35Z",
_45
"date_updated": "2021-01-27T14:18:36Z",
_45
"business_name": "Owl, Inc.",
_45
"business_street_address": "123 Main Street",
_45
"business_street_address2": "Suite 101",
_45
"business_city": "Anytown",
_45
"business_state_province_region": "AA",
_45
"business_postal_code": "11111",
_45
"business_country": "US",
_45
"business_website": "http://www.company.com",
_45
"business_contact_first_name": "firstname",
_45
"business_contact_last_name": "lastname",
_45
"business_contact_email": "email@company.com",
_45
"business_contact_phone": "+1231231234",
_45
"notification_email": "support@company.com",
_45
"use_case_categories": [
_45
"TWO_FACTOR_AUTHENTICATION",
_45
"MARKETING"
_45
],
_45
"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",
_45
"production_message_sample": "lorem ipsum",
_45
"opt_in_image_urls": [
_45
"https://zipwhiptestbusiness.com/images/image1.jpg",
_45
"https://zipwhiptestbusiness.com/images/image2.jpg"
_45
],
_45
"opt_in_type": "VERBAL",
_45
"message_volume": "1,000",
_45
"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",
_45
"tollfree_phone_number_sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"rejection_reason": null,
_45
"error_code": null,
_45
"edit_expiration": null,
_45
"edit_allowed": null,
_45
"rejection_reasons": null,
_45
"resource_links": {},
_45
"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"external_reference_id": null
_45
}


6. Submission Statuses and Notifications

6-submission-statuses-and-notifications page anchor

If your Toll-Free phone number has not been submitted for verification or the verification was Rejected or is filtered for spam, you will get the error code (30032): Toll-Free Number has not been verified as a response. To avoid this scenario, you should submit your Toll-Free phone number for verification as soon as possible. To reduce the risk of message filtering on Toll-Free traffic toward all major networks in the US and some in Canada, you'll need to adhere to your stated use case and all applicable rules, such as Twilio'sMessaging Policy(link takes you to an external page). For more information, see this support article(link takes you to an external page).

Upon a successful completion of the verification request, your phone numbers will be moved to Twilio-Verified and have full access to the A2P sending as well as the least amount of filtering applied to the traffic.

Submission StatusWhat's happening?Toll-Free phone number traffic.
PENDING_REVIEWTwilio's systems are processing the request and has not yet been sent to Verification Ops for review.The toll-free phone number is Restricted.
IN_REVIEWVerification Ops have accepted the submission, it's in their queue.The toll-free phone number is in a Pending verification state.
TWILIO_APPROVEDVerification submission has been verified.The toll-free phone number is Verified.
TWILIO_REJECTEDVerification submission has been resolved, but it was rejected. Depending on the error code and if the submission is re-submittable, when no edit is received within 7 days, the submissions will expire. It's best to edit and resubmit within 7 days. IF the submission is re-submittable, he submission will remain and it's editable, but after 7 days, the toll-free phone number remains in Restricted until the resubmission is received. An expired submission will be reviewed, but is no longer prioritized, so time to process is similar to a new submission.If re-submittable, the Toll-Free phone number is Pending. If not re-submittable, the Toll-Free phone number is Blocked. If it's after the 7-day resubmission response window, the toll-free phone number is Restricted. See more about traffic limits here(link takes you to an external page).

Please see our support article on Toll-Free Message Verification for US/Canada(link takes you to an external page) for more information.

Learning the Status of your Toll-Free Verification Submission

learning-the-status-of-your-toll-free-verification-submission page anchor

There are four different ways to learn the current status of any TFV submission.

  • The first of these, discussed and illustrated in Sections 3 and 4 above, involve directly polling the Messaging API at whatever interval, specifying your account SID and using either a GET (list) request to return records for all TFV requests in your account, or a GET with the TollfreeVerificationSID specified to return a status record for that TFV submission alone. As shown above, all records returned will include a status parameter, and in the case of REJECTED TFV submissions, the record(s) returned will also include rejection_reason and error_code parameters which will be very useful in troubleshooting a rejected submission.
  • In addition to directly polling the Messaging API, you can query the status of a TFV submission at any time via the Twilio Console, by navigating to Phone Numbers > Manage > Active Numbers , and inspecting the status of any particular TF number for which you've submitted a Verification application; for more detail on this see our Console TFV Onboarding Guide .

Of course, the challenge with either of the above methods is that you only learn of status changes to your TFV submissions when you actively seek out their status. But there are two other methods that push a status change event to you, so that you can learn about it in closer to real time.

  • The first of these is email notification , about which you can learn in this section below . This method requires that the notificationEmail parameter be populated with a valid email address at the point when a TFV submission is posted.
  • The second of these is via Webhooks , using a Twilio product called Event Streams . This procedure is detailed below as well.

If your submission was rejected, you can edit your submission if the Status Code allows for it. It's best to edit and resubmit within 7 days. Depending on the error code and if the submission is re-submittable, when no edit is received within 7 days, the submissions will expire. IF re-submittable, the submission will remain and it's editable, but after 7 days, the toll-free phone number remains in Restricted until the resubmission is received. An expired submission will be reviewed, but is no longer prioritized, so time to process is similar to a new submission. See more about TWILIO_REJECTED status here.

For information about forbidden SMS and MMS use cases, please check the Questionable SMS and MMS Message Categories in the US and Canada(link takes you to an external page) support article.

The following table shows rejection reasons after Twilio has reviewed and rejected a verification request and the possible solutions.

Rejection codes and solutions

Rejection reason codeCategoryResubmittable?
30437Edit time expiredYes
30440Unknown errorNo
30441Content violationNo
30442Campaign violationNo
30443Disallowed ContentNo
30444High RiskNo
30445Invalid InformationYes
30446Opt-In ErrorYes
30447Phone Number ErrorYes
30448Age GateYes
30449Invalid Sample Message URLYes
30451Address is invalidYes
30452Email is invalidYes

A status update of your Toll-Free phone number verification request will be sent via an email notification.

When submitting a Toll-Free verification request, you can pass to the notificationEmail parameter the email address where you want the notification to be sent. If an ISV, you would enter the ISV's email address there. The value in the notificationEmail receives an email once the status of the verification request changes.

Webhooks & Event Streams

webhooks--event-streams page anchor

The Messaging Compliance API utilizes Twilio's Event Streams product to deliver verification status updates. Event Streams provides a common interface to receive and deliver events based on your subscriptions. You can now subscribe to messaging compliance webhooks events and be notified of your Toll-Free verification request result through Event Streams.

Webhooks Setup using Event Streams, via Twilio Console Sink in this context means a destination for Events you want to subscribe to. In this case it will be a Webhook sink, i.e. a specific URL you have designated on your own site that will monitor for newly-raised events, and be able to programmatically parse the event payloads and notify you as appropriate. As with email notifications these are 'push' notifications, but with Webhooks and Event Streams you can have a good deal more control over which events are actually raised to your own awareness. For example you could design your Webhook page to react only to APPROVED TFVs, or only to REJECTED ones, or to send your own notifications to different parties based on approved vs rejected statuses. You could also set a timer upon receiving an IN_REVIEW status, such that you are programmatically notified after some number of days if that TFV application doesn't have a further change in status.

To create the requisite Sinks and Subscriptions in this case, navigate to your Twilio Console, and follow the instructions below:

  1. Click on the Explore Products link in the left navigation pane and select Event Streams.

    TF API - Events Streams Step 1.
  2. Select a new Sink Type of Webhook and Create a new Webhook Sink.

    TF API - Events Streams Step 2.
  3. Enter a description in the Create new Subscription page and scroll to the Messaging - Toll Free Verification section.

    TF API - Events Streams Step 3.
  4. Give your Source a friendly name (i.e, Toll Free Verification Events). Under Source events, navigate to Toll Free Verification and select the events that you would like to become the Source of your stream. You will find four types of events (but NOTE again that you do not need to subscribe to ALL of these events; in this case one might want to omit Pending Review, for example, as it marks a transitory state before the TF ecosystem even begins its review). The four event types are:

    • Pending Review
    • In Review
    • Twilio Approved
    • Twilio Rejected.
WebhooksList.

Next, click on the Save Source button. After that, a confirmation toast will be shown with the following information: "Your new Source has been successfully created".

  1. Finally, you'll see a screen with your selected Event types.
    TF API - Events Streams Step 4.

Event Types & Payload:

It is important to understand the json payload format for each of the TFV event types that you might subscribe to, so that your Webhook code can parse and respond to it appropriately.

In Review: this means that Verification Ops have accepted the submission, and it's in their queue to be processed. The verificationstatus parameter indicates this with the "in_review" status. Other important parameters here are accountsid (the account within which the TFV submission has actually been submitted, which might be a child account); the parentaccountsid if applicable; the phonenumbersid which identifies the actual toll-free number to which this verification event applies; the tollfreeverificationsid which identifies the TFV application itself (this will have been returned when the application was submitted, and allows you to track this submission through its lifecycle); and finally the time timestamp, which would be useful if one wanted to measure how long this TFV application has been in review.


_22
[
_22
{
_22
"data": {
_22
"accountsid": "ACXXXXXXXX",
_22
"customerprofilesid": "BUXXXXXXXXX",
_22
"parentaccountsid": "ACXXXXXXXX",
_22
"phonenumbersid": "PNXXXXXXXXX",
_22
"processeddate": 1677105415122,
_22
"regulateditemsid": "RAXXXXXXXXX",
_22
"tollfreeverificationsid": "HHXXXXXXXXX",
_22
"trustproductsid": "ITXXXXXXXXXX",
_22
"verificationstatus": "in_review"
_22
},
_22
"datacontenttype": "application/json",
_22
"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationRequested/1",
_22
"id": "CE000000000000000000000000000000",
_22
"source": "CA000000000000000000000000000000",
_22
"specversion": "1.0",
_22
"time": "2021-05-05T05:51:19.000Z",
_22
"type": "com.twilio.messaging.compliance.toll-free-verification.requested"
_22
}
_22
]

Twilio Approved: this means that the Verification submission has been successfully approved; this TF number is now verified and ready for use. Because this is the happy path, no further action is required on your part. Here, beyond the status, you'll want to note the tollfreeverificationsid itself, possibly the phonenumbersid to ensure that you have these correlated, and likely the accountsid if you are an ISV tracking the status of TFV applications for many customers.


_22
[
_22
{
_22
"data": {
_22
"accountsid": "ACXXXXXXXXX",
_22
"customerprofilesid": "BUXXXXXXXX",
_22
"parentaccountsid": "ACXXXXXXXXXX",
_22
"phonenumbersid": "PNXXXXXXXXX",
_22
"processeddate": 1677105415122,
_22
"regulateditemsid": "RAXXXXXXXXX",
_22
"tollfreeverificationsid": "HHXXXXXXXXX",
_22
"trustproductsid": "ITdc6d302901619ba6aa190cb1993cbeb5",
_22
"verificationstatus": "twilio_approved"
_22
},
_22
"datacontenttype": "application/json",
_22
"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationRequestApproved/1",
_22
"id": "CE000000000000000000000000000000",
_22
"source": "CA000000000000000000000000000000",
_22
"specversion": "1.0",
_22
"time": "2021-05-05T05:51:19.000Z",
_22
"type": "com.twilio.messaging.compliance.toll-free-verification.request-approved"
_22
}
_22
]

Twilio Rejected:

Verification submission has been resolved, but the submission was rejected. How you respond to this will depend on the payload details, particularly errorcode and errordescription. See this section above for details on the meaning of different error codes, and which ones are re-submittable (again, some are not, e.g. for disallowed or high-risk content).

Assuming the rejected application is re-submittable, it is best to resubmit within 7 days of the rejection (based on the processdate). Resubmissions within this window will go to a prioritized resubmission queue. After 7 days the submission will "expire", meaning it can still be re-submitted for review but will no longer be prioritized, so its turnaround time will be similar to a new submission.


_24
[
_24
{
_24
"data": {
_24
"accountsid": "ACXXXXXXXXX",
_24
"customerprofilesid": "BUXXXXXXXXX",
_24
"errorcode": 30445,
_24
"errordescription": "Invalid Information",
_24
"parentaccountsid": "ACXXXXXXXXXX",
_24
"phonenumbersid": "PNXXXXXXXXXX",
_24
"processeddate": 1677105415122,
_24
"regulateditemsid": "RAXXXXXXXXXXX",
_24
"tollfreeverificationsid": "HHXXXXXXXXXX",
_24
"trustproductsid": "ITXXXXXXXXXX",
_24
"verificationstatus": "twilio_rejected"
_24
},
_24
"datacontenttype": "application/json",
_24
"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationRequestRejected/1",
_24
"id": "CE000000000000000000000000000000",
_24
"source": "CA000000000000000000000000000000",
_24
"specversion": "1.0",
_24
"time": "2021-05-05T05:51:19.000Z",
_24
"type": "com.twilio.messaging.compliance.toll-free-verification.request-rejected"
_24
}
_24
]

Rejection Expired: Although the verificationstatus parameter here will still be "twilio-rejected", as in the previous case, the event type (type parameter) is now com.twilio.messaging.compliance.toll-free-verification.expired as shown below, as opposed to com.twilio.messaging.compliance.toll-free-verification.request-rejected as in the previous return code sample. This indicates that a rejected TFV submission has exceeded its initial 7-day window. Again, it can STILL be re-submitted in this case (if it's re-submittable), and the resubmission itself would still need to address the same issues it would have while within the window. One would simply expect the review time in this case to be more like a new-submission review time. The toll-free phone number is also reset to unverified, so no messaging traffic is allowed.


_22
[
_22
{
_22
"data": {
_22
"accountsid": "ACXXXXXXXXX",
_22
"customerprofilesid": "BUXXXXXXXXX",
_22
"parentaccountsid": "ACXXXXXXXXXX",
_22
"phonenumbersid": "PNXXXXXXXXXX",
_22
"processeddate": 1677105415122,
_22
"regulateditemsid": "RAXXXXXXXXXXX",
_22
"tollfreeverificationsid": "HHXXXXXXXXXX",
_22
"trustproductsid": "ITXXXXXXXXXX",
_22
"verificationstatus": "twilio_rejected"
_22
},
_22
"datacontenttype": "application/json",
_22
"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationExpired/1",
_22
"id": "CE000000000000000000000000000000",
_22
"source": "CA000000000000000000000000000000",
_22
"specversion": "1.0",
_22
"time": "2021-05-05T05:51:19.000Z",
_22
"type": "com.twilio.messaging.compliance.toll-free-verification.expired"
_22
}
_22
]


7. Delete a Verification submission record

7-delete-a-verification-submission-record page anchor

Currently customers can delete a toll-free messaging verification submission directly via Twilio API (here) or Console. Previously they had to create a support ticket.

Customers will need to have a toll-free messaging verification "in progress", "approved", or "rejected" in order to use the delete action. If the Toll Free verification has not yet been submitted ("not verified"), then the delete action will not perform.

(information)

Info

Pro Tip: Deleting the toll-free messaging verification record does not release the toll-free number from your Twilio Account.

When to use and not use this Delete feature

Verification StatusAction
No statusYou can't use the delete feature as it won't be available for this toll-free number. It means no Verification has been submitted yet, so there won't yet be a record for this number in the Verification workflow and the Toll-Free phone number is considered Restricted.
Verification in progressYou can use this delete feature on an existing, in-progress submission record in order to delete that record and submit a new verification if you need to update information that is incorrect. But only do this if the incorrect information pertains to the use-case or the opt-in flow, or incorrect business information such as an incorrect website url. Lesser issues should not impede verification and do not require deletion and re-submission. NOTE: Deleting an in-progress verification submission record, and submitting a new one, will move that submission to the back of the line for verification. Therefore, do NOT use delete if an in-progress verification simply seems to be taking too long (but you have no important information to change), as this will not expedite the process.
ApprovedYou could use this delete feature on an existing, approved Verification record if you wanted to subsequently change the use case and/or opt-in flow for that Verified TFN. You would then resubmit the Verification for this toll-free phone number with the new information. Again, this new submission would require it's own full-length review process. No such deletion/resubmission is required if you're only making minor changes to your use of the toll-free phone number for messaging, for example to change the anticipated MessageVolume.
RejectedIf a previous submission has been rejected with a Reason Code that is not Resubmittable, it is "not eligible for resubmission". Using this delete feature on that record is the only way to resubmit the same toll-free number for verification. But only do so if you have a clear understanding of what needs to be corrected (for example a mistyped or incorrect website URL, or an incomplete use case or opt-in description). If the previous submission has been rejected with a Reason Code that is Resubmittable, please use the existing Edit a rejected toll-free verification request to edit and resubmit receive expedited review. NOTE: Upon notice of a rejection, you have a 7-day window for re-submission in order to be eligible for expedited review. After this period, a re-submission is allowed, but it will move to the back of the line for review.

As indicated in the following code sample, for this delete call, other than the account_sid and auth_token that are required for all API calls, the only required paramater is the path SID, which is the Verification Record SID (format HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) for the Verification record you would like to delete. This is the same SID you would have used in e.g. Step 4 above to retrieve this Verification record. It is the sid originally returned in the response json when this record was first created.

Delete Verification record

delete-verification-record page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messaging.v1.tollfreeVerifications('HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();


8. List of Messaging Compliance API Error Codes

8-list-of-messaging-compliance-api-error-codes page anchor

When the Messaging Compliance API returns a status other than 200, we add an error code in the message body. This table enumerates and describes all the possible error codes.

Status CodeError MessageDescription
404 (Not found)Toll-Free verification not found.No record (HHXXX) was found for a given Toll-Free verification.
404No Toll-Free verification records found.No verification records found for a given Account SID.
400 (Precondition failed)Missing mandatory field name for submitting a verification.One or several required fields are missing.
400Email address is invalid.See email validation rules below. Applies to notificationEmail and businessContactEmail.
400Phone number is invalid.Applies to businessContactPhone and tollFreeNumber. Note: A U.S. Toll-Free number begins with one of the following three-digit codes: 800, 888, 877, 866, 855, 844 and 833.
400The messageVolume parameter is invalid.The messageVolume value submitted is not allowed.
400The useCase parameter is invalid.The useCase value submitted is not allowed.
400The optInType parameter is invalid.The optInType value submitted is not allowed.
400No values were submitted as part of a resubmission.The verification edit request must have at least one value.
400No values were different when resubmitting.There is no new data in the verification edit request. At least one field must have a new value.
422No primary profile for account.ISV's accountSid is missing a Trusthub primary profile.
422Provided Customer Profile is not approved.The primary or secondary Customer Profile has not yet been approved by Twilio (CT Ops), so it can't be used in Toll-Free verification.
422Provided Customer Profile is not of the right profile type.The profile provided is not an ISV starter or SCP.
422Provided Customer Profile does not exist.The primary/secondary/direct starter/ISV starter profile does not exist.
422Provided tollFreeNumber is not Toll-Free.The phone number submitted for verification needs to be a Toll-Free sender type.
409Tollfree verification cannot be submitted when another verification exists or is in progress.Another Toll-Free verification is in progress for this customer & Toll-Free number.
422TollFree phone number not found.The pnsid submitted cannot be found.
422Toll-Free phone number is not associated with an account.The pnsid submitted is not associated with the account SID.
500General/Server Error.General/Server Error.

Rate this page: