Menu

Expand
Rate this page:

Toll-Free Verification API Onboarding Guide

Effective November 8, all Toll-Free numbers must be verified before they can be used for sms messaging in the U.S. and Canada. As of that date, Toll-Free numbers will be blocked from messaging until they've been submitted for verification. Please see this support article for more information.

Overview

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:

Let's get started!

1. Getting Started

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.

High Throughput for Toll-Free

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

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

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.

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

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

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

TFV_ISV_CustomerProfiles-graphic

Learn how to Submit a Toll-Free Verification Request

2. Submit a Toll-Free Verification Request

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:

Option 2.1: A Customer Profile SID is not provided

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

Link to an image or document that shows the opt-in workflow where your users sign up for your SMS campaign. 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:

- VERBAL
- WEB_FORM
- PAPER_FORM
- VIA_TEXT
- 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:

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

Loading Code Sample...
        
        

        Submit a Toll-Free Verification Request

        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)

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

        Toll-Free Verification request parameters

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

        Toll-Free phone number SID

        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.

        Business Name

        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.

        Business Website

        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.

        Business Address

        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.

        Message Volume

        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.

        Use Case Category

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

        Production Message Sample

        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.

        Use Case Summary

        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 Type

        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 http://twil.io/terms and our Privacy Statement can be found at https://twil.io/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.

        TFV_WebFormExample



        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:

        TFV_TextKeywordCampaign

        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.

        Opt-in Image URLs

        Consent is one of the cornerstones of A2P messaging. Opt-In workflow description should briefly describe how the handset 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 providing their phone number: online/app (URL, screenshot/webpage), see in store (keyword, signage), or hears (IVR script/verbiage). Opt-in image URL parameter can contain a link to the web form or a hosted image file 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. It should demonstrate the Opt-In Type selected. 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 more detail about the opt in process, the better. The information provided for review 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 and examples 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:"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.

        Additional Information

        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

        Option 2.2: A Customer Profile SID is provided

        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:

        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_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

        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

        Link to an image or document that shows the opt-in workflow where your users sign up for your SMS campaign. 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:

        - VERBAL
        - WEB_FORM
        - PAPER_FORM
        - VIA_TEXT
        - 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.

        Loading Code Sample...
              
              

              Submit a Toll-Free Verification Request Using Existing Customer Profile

              Response: (400 Bad Request)

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

              Retrieve Customer Profile SID (optional)

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

              Request:

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

              Response:

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

              3. List Toll Free Verification Records (optional)

              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.

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

              GET (LIST):

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

              Request parameters:

              Parameter

              Required

              Description

              Status

              No

              It’s the status of the Toll Free verification.

              The status can be:

              • PENDING_REVIEW
              • IN_REVIEW
              • TWILIO_APPROVED
              • TWILIO_REJECTED

              TollfreePhoneNumberSid

              No

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

              PageSize

              No

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

              Loading Code Sample...
                    
                    

                    List Toll Free Verification Records

                    Request with optional Status parameter:

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

                    Request with optional TollfreePhoneNumberSid parameter:

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

                    Request with both optional parameters:

                    curl -X GET 'https://messaging.twilio.com/v1/Tollfree/Verifications?TollfreePhoneNumberSid=PNXXXXXX&Status=IN_REVIEW' \
                    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
                    Retrieve a single Toll-Free Verification Record (optional)

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

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

                    Loading Code Sample...
                          
                          

                          Retrieve a single Toll-Free Verification Record

                          Response of a Verification Rejected example:

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

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

                          5. Edit a rejected Toll-Free Verification request

                          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)

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

                                Resubmit a Toll-Free Verification Request

                                Now, let's check the Submission Statuses and Notifications

                                6. Submission Statuses and Notifications

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

                                Submitting your completed verification form places the Toll-Free phone number(s) in a Pending verification status, which allows for a higher daily volume and greatly reduces the chances of filtering while waiting for the final carrier approval. A Restricted Toll-Free number has daily/weekly/monthly limits and can still experience message filtering even when well below the daily limits.

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

                                Statuses:

                                Submission Status

                                What’s happening?

                                Toll-Free phone number traffic.

                                PENDING_REVIEW

                                Twilio's systems are processing the request and has not yet been sent to Verification Ops for review.

                                The toll-free phone number is Restricted.

                                IN_REVIEW

                                Verification Ops have accepted the submission, it’s in their queue.

                                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.

                                Depending on the error code and if the submission is re-submittable, when no edit is received within 7 days, the submissions will expire. It's best to edit and resubmit within 7 days. IF the submission is re-submittable, he submission will remain and it's editable, but after 7 days, the toll-free phone number remains in Restricted until the resubmission is received. An expired submission will be reviewed, but is no longer prioritized, so time to process is similar to a new submission.

                                If re-submittable, the Toll-Free phone number is Pending.

                                If not re-submittable, the Toll-Free phone number is Blocked.

                                If it's after the 7-day resubmission response window, the toll-free phone number is Restricted.

                                See more about traffic limits here.

                                Please see our support article on Toll-Free Message Verification for US/Canada for more information.

                                Learning the Status of your Toll-Free Verification Submission

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

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

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

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

                                Rejected Verifications

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

                                For information about forbidden SMS and MMS use cases, please check the Questionable SMS and MMS Message Categories in the US and Canada support article.

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

                                Rejection codes and solutions

                                Rejection reason code

                                Category

                                Resubmittable?

                                30437

                                Edit time expired

                                Yes

                                30441

                                Content violation

                                No

                                30442

                                Campaign violation

                                No

                                30443

                                Disallowed Content

                                No

                                30444

                                High Risk

                                No

                                30445

                                Invalid Information

                                Yes

                                30446

                                Opt-In Error

                                Yes

                                30447

                                Phone Number Error

                                Yes

                                30448

                                Age Gate

                                Yes

                                30449

                                Invalid Sample Message URL

                                Yes

                                30440

                                Unknown error

                                No

                                Email Notification

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

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

                                Webhooks & Event Streams

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

                                Webhooks Setup using Event Streams, via Twilio Console

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

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

                                1. Click on the Explore Products link in the left navigation pane and select Event Streams.
                                  TF API - Events Streams Step 1
                                2. Select a new Sink Type of Webhook and Create a new Webhook Sink.

                                  TF API - Events Streams Step 2

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

                                  TF API - Events Streams Step 3

                                4. Give your Source a friendly name (i.e, Toll Free Verification Events). Under Source events, navigate to Toll Free Verification and select the events that you would like to become the Source of your stream. You will find four types of events (but NOTE again that you do not need to subscribe to ALL of these events; in this case one might want to omit Pending Review, for example, as it marks a transitory state before the TF ecosystem even begins its review). The four event types are:
                                  • Pending Review
                                  • In Review
                                  • Twilio Approved
                                  • Twilio Rejectected.
                                    WebhooksList
                                    Next, click on the Save Source button. After that, a confirmation toast will be shown with the following information: “Your new Source has been successfully created”.
                                5. Finally, you'll see a screen with your selected Event types.
                                  TF API - Events Streams Step 4

                                Event Types & Payload:

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

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

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

                                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.

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

                                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.

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

                                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.

                                [
                                    {
                                        "data": {
                                            "accountsid": "ACXXXXXXXXX",
                                            "customerprofilesid": "BUXXXXXXXXX",
                                            "parentaccountsid": "ACXXXXXXXXXX",
                                            "phonenumbersid": "PNXXXXXXXXXX",
                                            "processeddate": 1677105415122,
                                            "regulateditemsid": "RAXXXXXXXXXXX",
                                            "tollfreeverificationsid": "HHXXXXXXXXXX",
                                            "trustproductsid": "ITXXXXXXXXXX",
                                            "verificationstatus": "twilio_rejected"
                                        },
                                        "datacontenttype": "application/json",
                                        "dataschema": "https://events-schemas.stage.twilio.com/TollFree.VerificationExpired/1",
                                        "id": "CE000000000000000000000000000000",
                                        "source": "CA000000000000000000000000000000",
                                        "specversion": "1.0",
                                        "time": "2021-05-05T05:51:19.000Z",
                                        "type": "com.twilio.messaging.compliance.toll-free-verification.expired"
                                    }
                                ]
                                ​
                                Next, let's learn how to delete an existing Toll-Free Number Verification

                                7. Delete a Verification submission record

                                Currently customers can delete a toll-free messaging verification submission directly via Twilio API. 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 be displayed.

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

                                When to use and not use this Delete feature

                                Verification 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 simply 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 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.

                                Loading Code Sample...
                                      
                                      

                                      Delete Verification record

                                      Finally, let's check out the list of API Error Codes

                                      8. List of Messaging Compliance API Error Codes

                                      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 Trusthub 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

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

                                      Rate this page:

                                      Need some help?

                                      We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                      Loading Code Sample...
                                            
                                            
                                            

                                            Thank you for your feedback!

                                            Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                            Sending your feedback...
                                            🎉 Thank you for your feedback!
                                            Something went wrong. Please try again.

                                            Thanks for your feedback!

                                            thanks-feedback-gif