Toll-Free Verification API Onboarding Guide
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 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:
- Getting Started
- Submit a Toll-Free Verification Request
- List Toll-Free Verification Records (optional)
- Retrieve a single Toll-Free Verification Record (optional)
- Edit a rejected & resubmittable Toll-Free Verification Request
- Submission Statuses and Notifications
- Delete a Toll-Free Verification Request
- List of Toll-Free Verification Error Codes
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).
Info
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).
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 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.
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.
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.
_10https://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. |
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}
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:
- 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.
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. |