Toll-Free Verification API Onboarding Guide

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).

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).

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.

Expand image

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:

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:

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)

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. Expand image 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: Expand image 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 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

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:

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

Request Parameters:

Response: (400 Bad Request)

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

Request:

Response:

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):

Request parameters:

Request with optional Status parameter:

Request with optional TollfreePhoneNumberSid parameter:

Request with both optional parameters:

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

GET:

Request parameter:

Response of a Verification Rejected example:

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)

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.

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.

1. Webhooks are highly recommended, using a Twilio product called Event Streams . This procedure is detailed below .
2. Email notification , which you can learn about 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.

With the next two options you only learn of status changes to your TFV submissions when you actively seek out their status.

3. The first of these, discussed and illustrated in Sections 3 and 4 above, involve directly polling the Messaging API, 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_reasons , error_code and edit_allowed parameters which will be useful in troubleshooting a rejected submission.
4. 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 TF number for which you've submitted a Verification application. For more detail see the Console TFV Onboarding Guide .

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

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:

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

   Expand image

2. Select a new Sink Type of Webhook and Create a new Webhook Sink.

   Expand image

3. Enter a description in the Create new Subscription page and scroll to the Messaging - Toll-Free Verification section.

   Expand image

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.

Expand image

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".

5. Finally, you'll see a screen with your selected Event types.
   Expand image

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.

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.

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.

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.

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.

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.

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.