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 for more information.
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 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).
If you are an ISV, see our support article for guidance on Toll-Free verification for ISVs.
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).
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 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.
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
.
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 subaccount 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.
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
:
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:
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:
Parameter | Field Type | Validation | Description |
---|---|---|---|
BusinessStreetAddress [required] | String | Number of characters <= 100 | The address of the business or organization using the Toll-Free phone number. For more information, see Business Address. |
BusinessStreetAddress2 [optional] | String | Number of characters <= 100 | The second address of the business or organization using the Toll-Free phone number. |
BusinessCity [required] | String | Number of characters <= 100 | The city of the business or organization using the Toll-Free phone number. |
BusinessStateProvinceRegion [required] | String | Number of characters <= 100 | The state/province or region of the business or organization using the Toll-Free phone number. |
BusinessPostalCode [required] | String | Number of characters <= 100 | The postal code of the business or organization using the Toll-Free phone number. |
BusinessCountry [required] | String | Number of characters <= 2 | The ISO country code of the business or organization using the Toll-Free phone number. |
BusinessContactFirstName [required] | String | Number of characters <= 500 | The first name of the contact for the business or organization using the Toll-Free phone number. |
BusinessContactLastName [required] | String | Number of characters <= 500 | The last name of the contact for the business or organization using the Toll-Free phone number. |
BusinessContactEmail [required] | String | Number 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] | String | Valid E.164 format phone number. | The phone number of the contact for the business or organization using the Toll-Free phone number. |
BusinessName [required] | String | Number of characters <= 500 | The name of the business or organization using the Toll-Free phone number. For more information, see Business Name. |
BusinessWebsite [required] | String | Number of characters <= 500 | The website of the business or organization using the Toll-Free phone number. For more information, see Business Website. |
NotificationEmail [required] | String | Number 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_ALERT | Choose 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] | String | Number of characters <= 500 | The explanation on how messaging is used by the business or organization. For more information, see Use Case Summary. |
ProductionMessageSample [required] | String | Number of characters <= 1000 | 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 <= 1000 | You 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] | String | One of the following exact values - VERBA - WEB_FOR - PAPER_FOR - VIA_TEX - MOBILE_QR_CODE | Describes 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] | String | One of the following exact values - 1 - 10 - 1,000 - 10,000 - 100,000 - 250,000 - 500,000 - 750,000 - 1,000,000 - 5,000,000 - 10,000,000+ | The monthly volume estimation of messages from the Toll-Free Number. For more information, see Message Volume. |
AdditionalInformation [optional] | String | Number of characters <= 500 | Additional info to help with the verification. For more information, see Additional Information. |
TollfreePhoneNumberSid [required] | String | Valid 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] | String | Number 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. |
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createTollfreeVerification() {11const tollfreeVerification =12await client.messaging.v1.tollfreeVerifications.create({13additionalInformation:14"see our privacy policy here www.johnscoffeeshop.com/privacypolicy",15businessCity: "Anytown",16businessContactEmail: "email@company.com",17businessContactFirstName: "firstname",18businessContactLastName: "lastname",19businessContactPhone: "+1231231234",20businessCountry: "US",21businessName: "Owl, Inc.",22businessPostalCode: "11111",23businessStateProvinceRegion: "AA",24businessStreetAddress: "123 Main Street",25businessStreetAddress2: "Suite 101",26businessWebsite: "http://www.company.com",27externalReferenceId: "abc123xyz567",28messageVolume: "10",29notificationEmail: "support@company.com",30optInImageUrls: [31"https://zipwhiptestbusiness.com/images/image1.jpg",32"https://zipwhiptestbusiness.com/images/image2.jpg",33],34optInType: "VERBAL",35productionMessageSample: "lorem ipsum",36tollfreePhoneNumberSid: "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",37useCaseCategories: ["TWO_FACTOR_AUTHENTICATION", "MARKETING"],38useCaseSummary:39"This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",40});4142console.log(tollfreeVerification.sid);43}4445createTollfreeVerification();
1{2"sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"regulated_item_sid": null,5"customer_profile_sid": null,6"trust_product_sid": null,7"status": "PENDING_REVIEW",8"date_created": "2021-01-27T14:18:35Z",9"date_updated": "2021-01-27T14:18:36Z",10"business_name": "Owl, Inc.",11"business_street_address": "123 Main Street",12"business_street_address2": "Suite 101",13"business_city": "Anytown",14"business_state_province_region": "AA",15"business_postal_code": "11111",16"business_country": "US",17"business_website": "http://www.company.com",18"business_contact_first_name": "firstname",19"business_contact_last_name": "lastname",20"business_contact_email": "email@company.com",21"business_contact_phone": "+1231231234",22"notification_email": "support@company.com",23"use_case_categories": [24"TWO_FACTOR_AUTHENTICATION",25"MARKETING"26],27"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",28"production_message_sample": "lorem ipsum",29"opt_in_image_urls": [30"https://testbusiness.com/images/image1.jpg",31"https://testbusiness.com/images/image2.jpg"32],33"opt_in_type": "VERBAL",34"message_volume": "10",35"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",36"tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",37"rejection_reason": null,38"error_code": null,39"edit_expiration": null,40"edit_allowed": null,41"rejection_reasons": null,42"resource_links": {},43"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",44"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)
1{2"code": 422,3"message": "Provided customer profile is not approved"4}
This section provides a deeper description with examples of some of the above-mentioned request parameters.
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:
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:
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.
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.
OptInType | Examples: |
---|---|
VERBAL | Twilio 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_FORM | An 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. Build your own SMS Opt-In template here NOTE: If you choose WEB_FORM, you must provide the link to it in the OptInImageURLs parameter |
PAPER_FORM | An 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_TEXT | A Keyword campaign example: NOTE: If you choose VIA_TEXT, you must provide the keyword campaign info in the OptInImageURLs document |
MOBILE_QR_CODE | A 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 detailed the information about the opt-in process, the better. The information provided for review within the OptInImageUrls example should be clear and allow for verification of what specifically the customer does to opt in/sign up to receive SMS from the end-user business.
EXAMPLES
✔ Approved Example: http://www.johnscoffeeshop.com/signupforsms
This is a direct URL to the opt-in sign up page.
✔ Approved Example:http://www.johnscoffeeshop.com/image123.png
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
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
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
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:
Request Parameters:
Parameter | Field Type | Validation | Description |
---|---|---|---|
CustomerProfileSid [required] | String | The 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] | String | Number of characters <= 500 | The name of the business or organization using the Toll-Free phone number. For more information, see Business Name. |
BusinessWebsite [required] | String | Number of characters <= 500 | The website of the business or organization using the Toll-Free phone number. For more information, see Business Website. |
NotificationEmail [required] | String | Number 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] | String | One 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_AUTHENTICATION - ACCOUNT_NOTIFICATION - CUSTOMER_CARE - CHARITY_NONPROFIT - DELIVERY_NOTIFICATION - FRAUD_ALERT_MESSAGING - EVENT - HIGHER_EDUCATION - K1 - MARKETING - POLLING_AND_VOTING_NON_POLITICAL - POLITICAL_ELECTION_CAMPAIGN - PUBLIC_SERVICE_ANNOUNCEMENT - SECURITY_ALERT | Choose 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] | String | Number of characters <= 500 | Explains how messaging is used by the business or organization. For more information, see Use Case Summary. |
ProductionMessageSample [required] | String | Number of characters <= 1000 | It'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 <= 1000 | You 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] | String | One of the following exact values - VERBA - WEB_FOR - PAPER_FOR - VIA_TEX - MOBILE_QR_CODE | Describes 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] | String | Valid 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] | String | Number of characters <= 500 | Additional documentation provided by the customer. For more information, see Additional Information. |
ExternalReferenceId [optional] | String | 50 chars 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. |
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createTollfreeVerification() {11const tollfreeVerification =12await client.messaging.v1.tollfreeVerifications.create({13additionalInformation:14"see our privacy policy here www.johnscoffeeshop.com/privacypolicy",15businessName: "Owl, Inc.",16businessWebsite: "http://www.company.com",17customerProfileSid: "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",18externalReferenceId: "abc123xyz567",19messageVolume: "10",20notificationEmail: "support@company.com",21optInImageUrls: [22"https://zipwhiptestbusiness.com/images/image1.jpg",23"https://zipwhiptestbusiness.com/images/image2.jpg",24],25optInType: "VERBAL",26productionMessageSample: "lorem ipsum",27tollfreePhoneNumberSid: "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",28useCaseCategories: ["TWO_FACTOR_AUTHENTICATION", "MARKETING"],29useCaseSummary:30"This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",31});3233console.log(tollfreeVerification.sid);34}3536createTollfreeVerification();
1{2"sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"regulated_item_sid": null,6"trust_product_sid": null,7"business_name": "Owl, Inc.",8"status": "PENDING_REVIEW",9"date_created": "2021-01-27T14:18:35Z",10"date_updated": "2021-01-27T14:18:36Z",11"business_street_address": "123 Main Street",12"business_street_address2": "Suite 101",13"business_city": "Anytown",14"business_state_province_region": "AA",15"business_postal_code": "11111",16"business_country": "US",17"business_website": "http://www.company.com",18"business_contact_first_name": "firstname",19"business_contact_last_name": "lastname",20"business_contact_email": "email@company.com",21"business_contact_phone": "+11231231234",22"notification_email": "support@company.com",23"use_case_categories": [24"TWO_FACTOR_AUTHENTICATION",25"MARKETING"26],27"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",28"production_message_sample": "lorem ipsum",29"opt_in_image_urls": [30"https://testbusiness.com/images/image1.jpg",31"https://testbusiness.com/images/image2.jpg"32],33"opt_in_type": "VERBAL",34"message_volume": "10",35"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",36"tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",37"rejection_reason": null,38"error_code": null,39"edit_expiration": null,40"edit_allowed": null,41"rejection_reasons": null,42"resource_links": {},43"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",44"external_reference_id": "abc123xyz567"45}
Response: (400 Bad Request)
1{2"code": 400,3"message": "Missing mandatory fields for submitting a verification"4}
You can select an existing Customer Profile SID associated to your Twilio Account by making a request to the TrustHub API as following:
Request:
1curl -X GET 'https://trusthub.twilio.com/v1/CustomerProfiles?PageSize=2' \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Response:
1{2"sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",4"policy_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",5"friendly_name": "friendly_name",6"status": "draft",7"valid_until": null,8"email": "email",9"status_callback": "http://www.example.com",10"date_created": "2019-07-30T22:29:24Z",11"date_updated": "2019-07-31T01:09:00Z",12"url":13"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",14"links": {15"customer_profiles_entity_assignments":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/EntityAssignments",16"customer_profiles_evaluations":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Evaluations",17"customer_profiles_channel_endpoint_assignment":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ChannelEndpointAssignments"18},19{20"sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",21"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",22"policy_sid": "RNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",23"friendly_name": "another_friendly_name",24"status": "twilio-approved",25"valid_until": null,26"email": "another_email",27"status_callback": "http://www.example.com",28"date_created": "2019-07-28T12:33:04Z",29"date_updated": "2019-07-29T10:59:19Z",30"url": "https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",31"links": {32"customer_profiles_entity_assignments":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/EntityAssignments",33"customer_profiles_evaluations":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Evaluations",34"customer_profiles_channel_endpoint_assignment":"https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ChannelEndpointAssignments"35}36}
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.
GET
(LIST):
https://messaging.twilio.com/v1/Tollfree/Verifications
Request parameters:
Parameter | Required | Description |
---|---|---|
Status | No | The status of the Toll-Free verification. The status can be: PENDING_REVIEW, IN_REVIEW, TWILIO_APPROVED, TWILIO_REJECTED |
TollfreePhoneNumberSid | No | The SID of the Toll-Free phone number. You can use it to find the Toll-Free verification record (PNXXXXXX) . |
PageSize | No | The number of verification returned in a request. The maximum value is 50. |
IncludeSubAccounts | No | Boolean to indicate if verification records for all subaccounts should be included in the response. |
PageToken | No | The token for requesting the next page, can be retrieved from the previous page's PageToken response property. Must be absent when requesting the first page. |
Request with optional Status
parameter:
1curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?Status=IN_REVIEW' \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Request with optional TollfreePhoneNumberSid
parameter:
1curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?TollfreePhoneNumberSid=PNXXXXXXXXX' \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Request with both optional parameters:
1curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?TollfreePhoneNumberSid=PNXXXXXX&Status=IN_REVIEW' \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Request with optional IncludeSubAccounts
parameter:
1curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?IncludeSubAccounts=True' \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
Twilio now supports multiple rejection reasons as seen in the rejection_reasons
list. While rejection_reason
and error_code
are still supported, we suggest migrating to the rejection_reasons
list, so that you get all the rejection reasons. Refer to the rejected verifications section for a full list of error codes.
Also note: edit_allowed
tells you if the verification can be resubmitted and rejected_on
and edit_expiration
help you manage the rejection.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listTollfreeVerification() {11const tollfreeVerifications =12await client.messaging.v1.tollfreeVerifications.list({ limit: 20 });1314tollfreeVerifications.forEach((t) => console.log(t.sid));15}1617listTollfreeVerification();
1{2"meta": {3"page": 0,4"page_size": 50,5"first_page_url": "https://messaging.twilio.com/v1/Tollfree/Verifications?Status=TWILIO_APPROVED&ExternalReferenceId=abc123xyz567&TollfreePhoneNumberSid=PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&IncludeSubAccounts=false&PageSize=50&Page=0",6"previous_page_url": null,7"next_page_url": null,8"key": "verifications",9"url": "https://messaging.twilio.com/v1/Tollfree/Verifications?Status=TWILIO_APPROVED&ExternalReferenceId=abc123xyz567&TollfreePhoneNumberSid=PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&IncludeSubAccounts=false&PageSize=50&Page=0"10},11"verifications": [12{13"sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",14"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",15"customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",16"trust_product_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",17"regulated_item_sid": "RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",18"date_created": "2021-01-27T14:18:35Z",19"date_updated": "2021-01-27T14:18:36Z",20"business_name": "Owl, Inc.",21"business_street_address": "123 Main Street",22"business_street_address2": "Suite 101",23"business_city": "Anytown",24"business_state_province_region": "AA",25"business_postal_code": "11111",26"business_country": "US",27"business_website": "http://www.company.com",28"business_contact_first_name": "firstname",29"business_contact_last_name": "lastname",30"business_contact_email": "email@company.com",31"business_contact_phone": "+11231231234",32"notification_email": "support@company.com",33"use_case_categories": [34"TWO_FACTOR_AUTHENTICATION",35"MARKETING"36],37"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",38"production_message_sample": "lorem ipsum",39"opt_in_image_urls": [40"https://testbusiness.com/images/image1.jpg",41"https://testbusiness.com/images/image2.jpg"42],43"opt_in_type": "VERBAL",44"message_volume": "1,000",45"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",46"tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",47"status": "TWILIO_APPROVED",48"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",49"rejection_reason": null,50"error_code": null,51"edit_expiration": null,52"edit_allowed": null,53"rejection_reasons": null,54"resource_links": {55"customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",56"trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",57"channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments/RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"58},59"external_reference_id": "abc123xyz567"60}61]62}
This step returns a single Toll-Free verification record for an account that has been submitted to Twilio.
GET
:
https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXX
Request parameter:
Parameter | Required | Description |
---|---|---|
TollfreeVerificationSID | Yes | The SID of the Toll-Free verification record (HHXXXXXXXXXX). |
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchTollfreeVerification() {11const tollfreeVerification = await client.messaging.v112.tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.fetch();1415console.log(tollfreeVerification.sid);16}1718fetchTollfreeVerification();
1{2"sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"trust_product_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"regulated_item_sid": "RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",7"date_created": "2021-01-27T14:18:35Z",8"date_updated": "2021-01-27T14:18:36Z",9"business_name": "Owl, Inc.",10"business_street_address": "123 Main Street",11"business_street_address2": "Suite 101",12"business_city": "Anytown",13"business_state_province_region": "AA",14"business_postal_code": "11111",15"business_country": "US",16"business_website": "http://www.company.com",17"business_contact_first_name": "firstname",18"business_contact_last_name": "lastname",19"business_contact_email": "email@company.com",20"business_contact_phone": "+11231231234",21"notification_email": "support@company.com",22"use_case_categories": [23"TWO_FACTOR_AUTHENTICATION",24"MARKETING"25],26"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",27"production_message_sample": "lorem ipsum",28"opt_in_image_urls": [29"https://testbusiness.com/images/image1.jpg",30"https://testbusiness.com/images/image2.jpg"31],32"opt_in_type": "VERBAL",33"message_volume": "2000",34"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",35"tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",36"status": "TWILIO_APPROVED",37"rejection_reason": null,38"error_code": null,39"edit_expiration": null,40"edit_allowed": null,41"rejection_reasons": null,42"resource_links": {43"customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",44"trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",45"channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelEndpointAssignments/RAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"46},47"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",48"external_reference_id": "abc123xyz567"49}
Response of a Verification Rejected example:
Twilio now supports multiple rejection reasons as seen in the rejection_reasons
list. While rejection_reason
and error_code
are still supported, we suggest migrating to the rejection_reasons
list, so that you get all the rejection reasons. Refer to the rejected verifications section for a full list of error codes.
Also note: edit_allowed
tells you if the verification can be resubmitted andrejected_on
and edit_expiration
can help you manage the rejection.
1{2"sid": "HHXXXXXXXX",3"account_sid": "AACXXXXXXXX",4"toll_free_phone_number_sid": "PNXXXXXXX",5"date_created": "2023-02-02T18:45:17.051372437Z",6"date_updated": "2023-02-02T18:45:20.03161371Z",7"status": "TWILIO_REJECTED",8"customer_profile_sid": "BUXXXXXXXX",9"trust_product_sid": "BUXXXXXXXX",10"regulated_item_sid": "RAXXXXXXXX",11"business_name": "Owl Inc.",12"business_street_address": "123 Main Street",13"business_street_address2": "Apt1",14"businesss_city": "Anytown",15"business_state_province_region": "AA",16"business_postal_code": "11111",17"business_country": "US",18"business_website": "http:www.company.com",19"business_contact_first_name": "firstname",20"business_contact_last_name": "lastname",21"business_contact_email": "email@company.com",22"business_contact_phone": "1231231234",23"notification_email": "test@example.com",24"use_case_categories": [25"EVENTS",26"CUSTOMER_CARE"27],28"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",29"production_message_sample": "lorem ipsum",30"opt_in_image_urls": ["https://owlinctestbusiness.com/images/image1.jpg"],31"opt_in_type": "MOBILE_QR_CODE",32"message_volume": "100",33"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",34"external_verification_request_id": "123-456",35"rejection_reason": "Invalid Information - Cant Validate URL",36"error_code": 30445,37"rejected_on": "2024-04-05T22:01:58.076Z",38"edit_expiration": "2024-04-05T22:01:58.076Z",39"edit_allowed": true,40"rejection_reasons": [41{42"reason": "Business information not valid",43"code": 30472,44}45{46"reason": "Cannot validate business website URL",47"code": 3047348}49],50"resource_links": {51"customer_profile": "https://trusthub.twilio.com/v1/CustomerProfiles/BUXXXXXXX",52"trust_product": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXX",53"channel_endpoint_assignment": "https://trusthub.twilio.com/v1/TrustProducts/BUXXXXXXX/ChannelEndpointAssignments/RAXXXXXXX"54},55"external_reference_id": null56}5758
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:
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)
1{2"code": 400,3"message": "Cannot edit an approved submission HHXXXXXXXXXXXXXXX",4"more_info": "https://www.twilio.com/docs/errors/400",5"status": 4006}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateTollfreeVerification() {11const tollfreeVerification = await client.messaging.v112.tollfreeVerifications("HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.update({14additionalInformation:15"see our privacy policy here www.johnscoffeeshop.com/privacypolicy",16businessCity: "Anytown",17businessContactEmail: "email@company.com",18businessContactFirstName: "firstname",19businessContactLastName: "lastname",20businessContactPhone: "+1231231234",21businessCountry: "US",22businessName: "Owl, Inc.",23businessPostalCode: "11111",24businessStateProvinceRegion: "AA",25businessStreetAddress: "123 Main Street",26businessStreetAddress2: "Suite 101",27businessWebsite: "http://www.company.com",28messageVolume: "1,000",29notificationEmail: "support@company.com",30optInImageUrls: [31"https://zipwhiptestbusiness.com/images/image1.jpg",32"https://zipwhiptestbusiness.com/images/image2.jpg",33],34optInType: "VERBAL",35productionMessageSample: "lorem ipsum",36useCaseCategories: ["TWO_FACTOR_AUTHENTICATION", "MARKETING"],37useCaseSummary:38"This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",39});4041console.log(tollfreeVerification.sid);42}4344updateTollfreeVerification();
1{2"sid": "HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"regulated_item_sid": null,5"customer_profile_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"trust_product_sid": null,7"status": "PENDING_REVIEW",8"date_created": "2021-01-27T14:18:35Z",9"date_updated": "2021-01-27T14:18:36Z",10"business_name": "Owl, Inc.",11"business_street_address": "123 Main Street",12"business_street_address2": "Suite 101",13"business_city": "Anytown",14"business_state_province_region": "AA",15"business_postal_code": "11111",16"business_country": "US",17"business_website": "http://www.company.com",18"business_contact_first_name": "firstname",19"business_contact_last_name": "lastname",20"business_contact_email": "email@company.com",21"business_contact_phone": "+1231231234",22"notification_email": "support@company.com",23"use_case_categories": [24"TWO_FACTOR_AUTHENTICATION",25"MARKETING"26],27"use_case_summary": "This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop",28"production_message_sample": "lorem ipsum",29"opt_in_image_urls": [30"https://testbusiness.com/images/image1.jpg",31"https://testbusiness.com/images/image2.jpg"32],33"opt_in_type": "VERBAL",34"message_volume": "1,000",35"additional_information": "see our privacy policy here www.johnscoffeeshop.com/privacypolicy",36"tollfree_phone_number_sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",37"rejection_reason": null,38"error_code": null,39"edit_expiration": null,40"edit_allowed": null,41"rejection_reasons": null,42"resource_links": {},43"url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",44"external_reference_id": null45}
If your Toll-Free phone number has not been submitted for verification or the verification was Rejected or messaging is filtered for spam, you will get messaging error code (30032): Toll-Free Number has not been verified. 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. For more information, see this support article.
Upon approval of the verification request, your phone number will be moved to Twilio-Approved and have full access to the A2P sending as well as the least amount of filtering applied to the traffic.
Submission Status | What's happening? | Toll-Free phone number traffic. |
---|---|---|
PENDING_REVIEW | Twilio's systems are processing the request, which has not yet been sent for verification. | The toll-free phone number is Restricted. |
IN_REVIEW | The submission has been accepted and is in the queue for verification. | The toll-free phone number is in a Pending verification state. |
TWILIO_APPROVED | Verification submission has been verified. | The toll-free phone number is Verified. |
TWILIO_REJECTED | Verification submission has been resolved, but it was rejected. If edit_allowed is true, you can edit your submission and resubmit it to Twilio for review. It's best to edit and resubmit within 7 days. When no edit is received within 7 days, the submission will expire. An expired submission will be reviewed, but is no longer prioritized, so time to process is similar to a new submission. | A US/CA toll-free phone number cannot send messages until the verification is TWILIO_APPROVED. |
There are four different ways to learn the current status of any TFV submission.
The first two push a status change event to you, so that you can be notified in near real time.
notificationEmail
parameter be populated with a valid email address at the point when a TFV submission is posted.
With the next two options you only learn of status changes to your TFV submissions when you actively seek out their status.
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_reasons
,
error_code
and
edit_allowed
parameters which will be useful in troubleshooting a rejected submission.
If your submission was rejected and edit_allowed
is true, you can edit your submission and resubmit it to Twilio for review. It's best to edit and resubmit within 7 days. When no edit is received within 7 days, the submission will expire. An expired submission will be reviewed, but is no longer prioritized, so the 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 support article.
The following table shows rejection reasons after Twilio has reviewed and rejected a toll-free verification request. Select the rejection reason code to review possible causes and solutions.
Rejection codes and solutions
Rejection reason code | Quick description | Resubmittable? |
---|---|---|
30437 | Edit time expired | Yes |
30440 | Unknown error | No |
30441 | Disallowed - SHAFT - Sex | No |
30442 | Business associated with a known Spam campaign | No |
30443 | Disallowed - Loan Marketing | No |
30444 | High risk - Third-party lead generation services and marketing: Fraud | No |
30445 | Could not verify Business | Yes |
30446 | Opt-in not sufficient - express consent required | Yes |
30447 | Phone Number Error - the toll-free phone number is not provisioned to Twilio | No |
30448 | Age Gate Not Present / Not Acceptable | Yes |
30449 | High risk - Public URL shortener in sample message | Yes |
30451 | Address is invalid | Yes |
30452 | Email is invalid | Yes |
30455 | Disallowed - SHAFT - Hate | No |
30456 | Disallowed - SHAFT - Alcohol | No |
30457 | Disallowed - SHAFT - Firearms | No |
30458 | Disallowed - SHAFT - Tobacco/Vape | No |
30459 | Disallowed - SHAFT - Cannabis/CBD | No |
30460 | Disallowed - Third party debt collection | No |
30461 | Disallowed - Gambling | No |
30462 | Disallowed - Sweepstakes | No |
30463 | Disallowed - Stock Alerts | No |
30464 | Disallowed - Cryptocurrency | No |
30465 | Disallowed - Risk Investment/Get Rich Quick Schemes | No |
30466 | Disallowed - Debt reduction | No |
30467 | Disallowed - Credit Repair | No |
30468 | Disallowed - Third party lead generation | No |
30469 | Disallowed - Illegal Substances/articles | No |
30470 | Disallowed - High risk - Third-party lead generation services and marketing: Deceptive marketing | No |
30471 | Disallowed - High risk - Non-secured URL in sample message | Yes |
30472 | Business information not valid | Yes |
30473 | Cannot validate business website URL | Yes |
30474 | Need end business | Yes |
30475 | Opt-in not sufficient - Cannot combine consent for messaging with requirement for service | Yes |
30476 | Opt-in not provided | Yes |
30477 | Opt-in not sufficient - Third party information sharing not allowed | Yes |
30478 | Phone number error - single phone number used for multiple businesses | Yes |
30479 | Justification needed for more than five toll-free phone numbers per businesses | Yes |
30480 | Business associated with a known Phishing campaign | No |
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.
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:
Click on the Explore Products link in the left navigation pane and select Event Streams.
Select a new Sink Type of Webhook and Create a new Webhook Sink.
Enter a description in the Create new Subscription page and scroll to the Messaging - Toll-Free Verification section.
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:
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".
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 Twilio has accepted the submission, and it's in the 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.
1[2{3"data": {4"accountsid": "ACXXXXXXXX",5"customerprofilesid": "BUXXXXXXXXX",6"parentaccountsid": "ACXXXXXXXX",7"phonenumbersid": "PNXXXXXXXXX",8"processeddate": 1677105415122,9"regulateditemsid": "RAXXXXXXXXX",10"tollfreeverificationsid": "HHXXXXXXXXX",11"trustproductsid": "ITXXXXXXXXXX",12"verificationstatus": "in_review"13},14"datacontenttype": "application/json",15"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationRequested/1",16"id": "CE000000000000000000000000000000",17"source": "CA000000000000000000000000000000",18"specversion": "1.0",19"time": "2021-05-05T05:51:19.000Z",20"type": "com.twilio.messaging.compliance.toll-free-verification.requested"21}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.
1[2{3"data": {4"accountsid": "ACXXXXXXXXX",5"customerprofilesid": "BUXXXXXXXX",6"parentaccountsid": "ACXXXXXXXXXX",7"phonenumbersid": "PNXXXXXXXXX",8"processeddate": 1701414000000,9"regulateditemsid": "RAXXXXXXXXX",10"tollfreeverificationsid": "HHXXXXXXXXX",11"trustproductsid": "ITdc6d302901619ba6aa190cb1993cbeb5",12"verificationstatus": "twilio_approved"13},14"datacontenttype": "application/json",15"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationRequestApproved/1",16"id": "CE000000000000000000000000000000",17"source": "CA000000000000000000000000000000",18"specversion": "1.0",19"time": "2021-05-05T05:51:19.000Z",20"type": "com.twilio.messaging.compliance.toll-free-verification.request-approved"21}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.
1[2{3"data": {4"accountsid": "ACXXXXXXXXX",5"parentaccountsid": "ACXXXXXXXXXX",6"tollfreeverificationsid": "HHXXXXXXXXXX",7"phonenumber": "+18002203994",8"phonenumbersid": "PNXXXXXXXXXX",9"customerprofilesid": "BUXXXXXXXXX",10"trustproductsid": "ITXXXXXXXXXX",11"regulateditemsid": "RAXXXXXXXXXX",12"verificationstatus": "twilio_rejected",13"errorcode": 30473,14"errorcodes": "30473,30475,30476",15"errordescription": "Website is not accessible / not available; Opt-in - Consent for messaging is a requirement for service; Opt-in - No opt-in provided",16"processeddate": 1701413000000,17"rejectiondate": 1701414000000,18"editexpiration": 1702018800000,19"editallowed": true20},21"datacontenttype": "application/json",22"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationRequestRejected/4",23"id": "ab80872e-ae4a-465b-b31c-61b82e815f66",24"source": "ab80872e-ae4a-465b-b31c-61b82e815f66",25"specversion": "1.0",26"time": "2021-05-05T05:51:19.000Z",27"type": "com.twilio.messaging.compliance.toll-free-verification.request-rejected"28}29]
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 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.
1[2{3"data": {4"accountsid": "ACXXXXXXXXX",5"customerprofilesid": "BUXXXXXXXXX",6"parentaccountsid": "ACXXXXXXXXXX",7"phonenumbersid": "PNXXXXXXXXXX",8"processeddate": 1677105415122,9"regulateditemsid": "RAXXXXXXXXXXX",10"tollfreeverificationsid": "HHXXXXXXXXXX",11"trustproductsid": "ITXXXXXXXXXX",12"verificationstatus": "twilio_rejected"13},14"datacontenttype": "application/json",15"dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationExpired/1",16"id": "CE000000000000000000000000000000",17"source": "CA000000000000000000000000000000",18"specversion": "1.0",19"time": "2021-05-05T05:51:19.000Z",20"type": "com.twilio.messaging.compliance.toll-free-verification.expired"21}22]23
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.
Pro Tip: Deleting the toll-free messaging verification record does not release the toll-free number from your Twilio Account.
Verification Status | Action |
---|---|
No status | You 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 progress | You 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 seems to be taking too long (but you have no important information to change), as this will not expedite the process. |
Approved | You 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. |
Rejected | If 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 parameter 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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteTollfreeVerification() {11await client.messaging.v112.tollfreeVerifications("HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.remove();14}1516deleteTollfreeVerification();
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 Code | Error Message | Description |
---|---|---|
404 (Not found) | Toll-Free verification not found. | No record (HHXXX) was found for a given Toll-Free verification. |
404 | No 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. |
400 | Email address is invalid. | See email validation rules below. Applies to notificationEmail and businessContactEmail. |
400 | Phone 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. |
400 | The messageVolume parameter is invalid. | The messageVolume value submitted is not allowed. |
400 | The useCase parameter is invalid. | The useCase value submitted is not allowed. |
400 | The optInType parameter is invalid. | The optInType value submitted is not allowed. |
400 | No values were submitted as part of a resubmission. | The verification edit request must have at least one value. |
400 | No values were different when resubmitting. | There is no new data in the verification edit request. At least one field must have a new value. |
422 | No primary profile for account. | ISV's accountSid is missing a Trust Hub primary profile. |
422 | Provided 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. |
422 | Provided Customer Profile is not of the right profile type. | The profile provided is not an ISV starter or SCP. |
422 | Provided Customer Profile does not exist. | The primary/secondary/direct starter/ISV starter profile does not exist. |
422 | Provided tollFreeNumber is not Toll-Free. | The phone number submitted for verification needs to be a Toll-Free sender type. |
409 | Toll-free 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. |
422 | TollFree phone number not found. | The pnsid submitted cannot be found. |
422 | Toll-Free phone number is not associated with an account. | The pnsid submitted is not associated with the account SID. |
500 | General/Server Error. | General/Server Error. |