Developer Guide to Toll-Free Verification

Time to read: 4 minutes

October 30, 2023

Written by

Twilio

Twilion

In light of the recent announcement that as of November 8, 2023, verification will be required for all Restricted (formerly called “Unverified”) toll-free phone numbers before they can be used for messaging, here’s a developer’s guide on toll-free registration using the Messaging Compliance API.

As an alternative method of registration (via UI), you can submit your verification directly from the Twilio Console by following our Console onboarding guide. However, the Messaging Compliance API is better suited for handling large quantities of registrations and seamlessly integrating into existing application workflows.

What is happening?

The messaging industry, along with Twilio, is continuing its shift towards a more compliant and transparent ecosystem to protect users from bad actors, spam, and unwanted communications. With Trusted Communications, Twilio is committed to partnering with the industry to build this trusted ecosystem so consumers are more likely to engage with legitimate messages from businesses and organizations.

Once submitted, toll-free numbers enter a Pending state and will continue having sending limits; however starting January 31, 2024, messages sent through a Pending toll-free number will be blocked and subject to messaging fees. The following are the current sending limits (not guaranteed maximums and are subject to change) for Pending numbers:

Daily: 2,000 message segments

Weekly: 6,000 message segments

Monthly: 10,000 message segments

What is a Message Segment?

Every builder is required to comply with these requirements. Although we understand that this process introduces friction and can slow you down, it’s one of the ways we work to ensure messages are protected from spam and bad actors. Taking these steps will enable you, as developers, to continue building and innovating with messaging.

What number type should developers be using?

Twilio offers a range of phone number types, each with its own capabilities and use cases.

10DLC, or 10-digit long codes, are standard phone numbers with messaging and voice capabilities. These numbers are great for use cases where localized, personalized communication is valued as 10DLC provides you with a local identity. These numbers offer high throughput and high delivery rates and are typically meant for individuals or businesses.

Toll-free numbers are also 10-digit phone numbers but they usually start with something like 1-833 or 1-888. They are great for universal brand identity and in the past were suited for support/sales lines but expanded their reach by supporting 2-way messaging, promotions, and notifications. Toll-free numbers are designated for medium/large business messaging and are not meant to be used for hobbyist developers.

If you are a student, hobbyist developer, or someone trying out Twilio messaging, we are exploring various solutions for you. One possibility is a Virtual Phone experience within the Twilio Console. More details will be provided closer to the launch.

If you are a business owner or ISV, you might consider 10DLC or toll-free, depending on your business needs (use case, deliverability requirements, etc).

I’m getting an error code (30032), what does that mean?

After sending a message with a toll-free number, you might get the error code (30032): Toll-free Number has not been verified. This could mean:

Your toll-free number has not been verified
Your toll-free verification request was rejected

To avoid this, submit your toll-free number for verification with the Messaging Compliance API, guidance in the following section.

I’m getting an error code (30007), what does this mean?

After sending a message with a toll-free number, you might get the error code 30007. This could mean:

Your toll-free phone number has been verified, but the message was filtered as spam
Your toll-free phone number has been submitted for verification (i.e. pending), but the message was filtered as spam

How do developers use the Messaging Compliance API for Toll-Free verification?

Option 1: Submit a Toll-Free Verification Request without a Customer Profile

Note: If you are an ISV (Independent Software Vendor), you’ll need to create a TrustHub primary Customer Profile for your business (not your customer's) and be in an APPROVED state.

Additionally, for each of your submissions, you need to provide your end-business (not your own) information as part of the submission. Toll-free verifications with ISV info will be rejected. If you set up your customers using an approved secondary Customer profile, you can then skip to Option 2: Submit a Toll-Free Verification Request with a Customer Profile.

To create a toll-free verification record, make a POST request to the API endpoint: https://messaging.twilio.com/v1/Tollfree/Verifications

Code snippets will be presented in cURL, however, the Messaging Compliance API supports other common server-side SDKs, each accompanied by relevant code samples.

If you have not created a Customer Profile, your request will need the required parameters and may look like this:

curl -X POST "https://messaging.twilio.com/v1/Tollfree/Verifications" \
# Business Address should be the business' physical location \
--data-urlencode "BusinessStreetAddress=123 Main Street" \
--data-urlencode "BusinessCity=Anytown" \
--data-urlencode "BusinessStateProvinceRegion=AA" \
--data-urlencode "BusinessPostalCode=11111" \
--data-urlencode "BusinessCountry=US" \
--data-urlencode "BusinessContactFirstName=firstname" \
--data-urlencode "BusinessContactLastName=lastname" \
--data-urlencode "BusinessContactEmail=email@company.com" \
--data-urlencode "BusinessContactPhone=+1231231234" \
# Business Name is the end business the customer is engaging with \
--data-urlencode "BusinessName=Owl, Inc." \
# Business Website is the end business website, business social media links are acceptable \
--data-urlencode "BusinessWebsite=http://www.company.com" \
--data-urlencode "NotificationEmail=support@company.com" \
# Use Case Categories cover one or more values that work best for the message traffic pattern. Make sure these match one of the allowed enums - see highlighted values. \
--data-urlencode "UseCaseCategories=ACCOUNT_NOTIFICATIONS" \
--data-urlencode "UseCaseCategories=MARKETING" \
# Use Case Summary explains how the message will be used by the business \
--data-urlencode "UseCaseSummary=This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop" \
# Production Message Sample is a sample message the end business will send. It should match the Use Case Category. \
--data-urlencode "ProductionMessageSample=lorem ipsum" \
# Opt-In Image URLs should demonstrate where the end-user opts in to your message \
--data-urlencode "OptInImageUrls=https://zipwhiptestbusiness.com/images/image1.jpg" \
# Opt-In Type should outline how end users provide consent to receive messages. Make sure these match one of the allowed enums - see highlighted values. \
--data-urlencode "OptInType=VERBAL" \
# Message Volume is the estimated volume you expect \
--data-urlencode "MessageVolume=10" \
--data-urlencode "TollfreePhoneNumberSid=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Explore more and find examples of the request parameters in our detailed guide on Toll-Free Verification request parameters.

Option 2: Submit a Toll-Free Verification Request with a Customer Profile

If you are an ISV submitting your Customer’s Profile, and you’ve already created a profile for them at Twilio, you can re-use it here.

This is best for ISVs who have created Secondary Customer Profiles at Twilio which are well-supported across products.

Your verification request will require different parameters, notably the Customer Profile SID.

To retrieve the Customer Profile SID, make a GET request like so:

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

Copy the Customer Profile SID (String starting with BU), from the response, and save it for later.

{
 "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"
  }
}

Using the copied Customer Profile SID from the previous request, make a new API request to the Verifications endpoint:

curl -X POST "https://messaging.twilio.com/v1/Tollfree/Verifications" \
# Customer Profile SID should be in an APPROVED state \
--data-urlencode "CustomerProfileSid=BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
--data-urlencode "BusinessName=Owl, Inc." \
--data-urlencode "BusinessWebsite=http://www.company.com" \
--data-urlencode "NotificationEmail=support@company.com" \
--data-urlencode "UseCaseCategories=ACCOUNT_NOTIFICATIONS" \
--data-urlencode "UseCaseCategories=MARKETING" \
--data-urlencode "UseCaseSummary=This number is used to send out promotional offers and coupons to the customers of John's Coffee Shop" \
--data-urlencode "ProductionMessageSample=lorem ipsum" \
--data-urlencode "OptInImageUrls=https://zipwhiptestbusiness.com/images/image1.jpg" \
--data-urlencode "OptInType=VERBAL" \
--data-urlencode "MessageVolume=10" \
--data-urlencode "TollfreePhoneNumberSid=PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Status of your Toll-Free Verification Request

After your POST, in either scenario, you’re response may look like this:

{
  "sid": "HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "regulated_item_sid": null,
  "customer_profile_sid": null,
  "trust_product_sid": null,
  "status": "PENDING_REVIEW",
  "date_created": "2021-01-27T14:18:35Z",
  "date_updated": "2021-01-27T14:18:36Z",
  "business_name": "Owl, Inc.",
  "business_street_address": "123 Main Street",
  "business_street_address2": null,
  "business_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": "support@company.com",
  "use_case_categories": [
    "ACCOUNT_NOTIFICATIONS",
    "MARKETING"
  ],
  "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://zipwhiptestbusiness.com/images/image1.jpg"
  ],
  "opt_in_type": "VERBAL",
  "message_volume": "10",
  "Additional_information": null,
  "tollfree_phone_number_sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "error_code": null,
  "edit_expiration": null,
  "resource_links": {},
  "url": "https://messaging.twilio.com/v1/Tollfree/Verifications/HHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "external_reference_id": null
}

In the request without a Customer Profile, for the response customer_profile_sid will be null as it’s an asynchronous process. You’ll get a webhook and an email with the customer_profile_sid.

In the response, you’ll see a status for your verification. To monitor this status, make a GET request with the Toll-Free number used for verification:

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

Here’s an overview of each verification status from the API:

Verification Status	Toll-Free Phone Number Traffic	Traffic Limits
PENDING_REVIEW	Restricted	Starting on November 8, 2023, ALL Restricted traffic will be blocked.
IN_REVIEW	Pending Verification	Sending Limits (not guaranteed) Daily: 2,000 message segments Weekly: 6,000 message segments Monthly: 10,000 message segments.
TWILIO_APPROVED	Approved	3 SMS segments per second by default, but can be increased.
TWILIO_REJECTED	If re-submittable, Pending. If not re-submittable, Blocked. If after the 7-day resubmission response window, Restricted	Blocked.

Additionally, you can list all Toll-Free verification records and view their status by making a GET request to the Verifications endpoint with an optional PageSize parameter:

curl -X GET "https://messaging.twilio.com/v1/Tollfree/Verifications?PageSize=20" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

In addition to making requests for monitoring the verification status, you can receive status updates through emails or get notified via webhooks through Event Streams.

Rejected Verifications or Error Codes

If your Toll-Free verification request has been rejected, you can edit and re-submit the verification depending on the returned error code. It's best to edit and resubmit within 7 days.

Alternatively, you can delete the verification submission in the Twilio Console.

The Future of Trusted Communications

This November 8, 2023 date when all messages sent from Restricted (or “Unverified”) toll-free phone numbers will be blocked is the next step towards a fully verified and trusted messaging ecosystem. As the messaging and communications ecosystem continues to change around the world, Twilio is dedicated to creating a trusted and compliant ecosystem for our customers.

For additional information, please reference our Docs on Toll-Free Verification API Onboarding.

Related Resources

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.

Developer Guide to Toll-Free Verification

Related Posts

Related Resources

From APIs to SDKs to sample apps

The latest ebooks, industry reports, and webinars

Twilio's developer community hub