Overview

Before you can use a toll-free number to send application-to-person (A2P) messages in the US and Canada, you must complete the toll-free number verification process. This process is meant to identify the sender, ensure compliance with the toll-free messaging best practices, and help eliminate bad actors from gaining access to the A2P channel. During verification, you will be asked to provide information about your company and reasons for using A2P messaging on toll-free numbers. If you’re a reseller, please provide information about the customers on whose behalf you will be sending text messages.

Submitting a toll-free verification request via APIs

Here’s how to use Plivo’s APIs to submit a verification request for your existing SMS-enabled toll-free numbers.

Java

Prerequisites To get started, you need a Plivo account — sign up with your work email address if you don’t have one already. If this is your first time using Plivo APIs, follow our instructions to set up a Java development environment.

import java.io.IOException;
import com.plivo.api.Plivo;
import com.plivo.api.exceptions.PlivoRestException;
import com.plivo.api.models.tollfree_verification.TollfreeVerification;
import com.plivo.api.models.tollfree_verification.TollfreeVerificationCreateResponse;

class TollfreeVerification {
  public static void main(String[] args) {
    Plivo.init("<auth_id>", "<auth_token>");
    try {
      TollfreeVerificationCreateResponse response = TollfreeVerification.creator(
        "<Your Plivo profile_uuid>",
        "<Your US/CA Plivo toll-free number>",
        "<Your use case from the list of allowed use cases>",
        "<A summary of your use case>",
        "<A valid optin image url>"
        "<Your message sample>",
        "<One of the allowed optin type>",
        "<The volume of message from one of the allowed values>").create();
      System.out.println(response);
    } catch (PlivoRestException | IOException e) {
      e.printStackTrace();
    }
  }
}

Toll-free verification status: from unverified to approved

The status of a toll-free, SMS-enabled number that you rent from Plivo is s set to unverified by default. The status will change to pending_verification when you submit the details required for verification. Messages sent from a number that’s listed as pending_verification may still be delivered. However, these messages are subject to carrier scrutiny and filtering and could be blocked. If your details are validated and your messages are approved, the status of the verification request changes to approved. If messages you intend to send are not allowed on the channel, or if the business details you provide cannot be validated, the status will change to unverified. As of November 8, 2023, unverified toll-free numbers cannot send messages to users in the US and Canada. These messages will be rejected by the carriers.

Submitting your business details

It is required to create a Plivo profile and use the profile_uuid to start the toll-free verification process via API. Your profile should contain accurate, up-to-date business details. Failing to provide these details using our profile APIs will cause your request to be rejected. Reseller submission If you are a reseller, you need to create a profile for your business first. This should be your primary profile. For each customer on whose behalf you intend to send messages, you should create a secondary profile. The profile_uuid of the relevant secondary profile should be submitted for toll-free verification along with the toll-free number you intend to use on their behalf. This is similar to the 10DLC registration process for resellers. What does this look like in practice? Consider a hypothetical reseller, Ovilp Corp., that provides a toll-free messaging platform for organizations that send messages in the US and Canada. Ovilp’s customers are hospitals and medical practitioners that might send messages such as

appointment alerts for patients;
marketing announcements to customers who have opted-in;
and two-factor authentication (2FA) codes for individuals to use to log in to patient portals.

Ovilp also has a console for their customers’ tech teams that requires 2FA to log in. This diagram shows this flow in action.

Toll-free verification status: from unverified to approved

Ovilp must submit verification requests for its business and each of its clients’ businesses separately and specify their respective use cases. Note: Resellers that don’t have toll-free messaging requirements for their own business still need to create a primary Plivo profile, but they can forgo verification submission for their own business and proceed to verify their customers directly. To ensure its own toll-free messages are verified, Ovilp must:

Create a primary profile with Plivo.
Use the profile_uuid and submit its 2FA use case for verification.

Then, per the diagram above, For Client A, Ovilp must:

Create a secondary profile with Plivo for Client A.
Use the secondary profile_uuid and submit for A’s marketing use case.

For Client B, Ovilp must:

Create a secondary profile with Plivo for Client B.
Use the secondary profile_uuid and submit a verification request for B’s use cases.
Toll-free verification for B’s use cases can be submitted through a single verification request as the verification APIs support the submission of multiple use cases through a single verification request.

Submitting message details

Toll-free number Use the number field to submit one toll-free number for verification per API request. Resellers can submit one toll-free number for each end user they service. Use case and use case summary The list of allowed use cases is outlined below.

Type	Details
2FA	Any two-factor authentication with passcodes used to unlock accounts.
ACCOUNT_NOTIFICATION	A notification sent to account holders about changes in accounts.
CUSTOMER_CARE	Customer care interactions by the support and other customer-facing teams.
DELIVERY_NOTIFICATION	Updates about the delivery of products and services.
FRAUD_ALERT	Notifications of suspicious behavior identified by the business.
HIGHER_EDUCATION	Messages sent by colleges, universities, and other educational institutions.
MARKETING	Communications related to time-bound events and sales.
POLLING_VOTING	Surveys, polling, and voting campaigns used for non-political purposes.
PUBLIC_SERVICE_ANNOUNCEMENT	Messages aimed at creating awareness about important topics.
SECURITY_ALERT	Notifications that alert users about a potential security breach.

Specific use cases are not allowed on toll-free numbers.

Deceptive marketing, including:
- Unsubstantiated claims, such as when a business claims that a product performs a certain way that it does not, accomplishes certain things it cannot, or brings an untrue benefit to consumers.
- Comparison inconsistencies, or situations in which a business says its product is comparable to brand-name products without sufficient evidence.
- Bait-and-switch tactics, or when a business markets a product it does not intend to deliver in terms of quality/function.
- Green or eco-friendly terms, or when a business advertises its products as environmentally-friendly or “green” despite knowing that goods are not produced under eco-friendly guidelines.
- False “made in the U.S.A.” claims.
Frauds and scams, including:
- Smishing, or SMS phishing scams, are fraudulent and deceptive messages sent via SMS to trick recipients into divulging sensitive personal information, financial details, or clicking on malicious links.
- Tax refund scams in which fraudsters pose as government agencies (like the IRS) and send text messages to individuals, claiming that they are eligible for a tax refund.
- Prize and lottery scams that make recipients believe they have won a contest or lottery, and then demand that the recipient pay or provide personal data to claim the winnings.
- Fake package delivery scams like SMS spoofing that impersonate reputable companies like Amazon and USPS.
- Financial scams in which scammers promise substantial—albeit fraudulent—investment opportunities, enticing recipients with returns that are too good to be true.
- Charity scams that exploit people’s goodwill. They are often from individuals or groups who pose as legitimate charity organizations to deceive people into donating to their malicious cause.
- Job offer scams that trick recipients into paying a specific amount to land a job. They may also persuade recipients to contact a number or click a link to accept a job offer.
- Romance scams in which scammers create fake online personas to manipulate and exploit unsuspecting people emotionally and financially.
- Government impersonation SMS scams where cyber attackers send fraudulent text messages pretending to be government officials or agencies.
- Tech support scams in which scammers pretend to be real tech support representatives from well-known companies.
Content related to SHAFT (sex, hate, alcohol, firearms, and tobacco)
Cannabis promotion/sale
Debt relief
High-risk financial services
Third-party lead generation services
Affiliate marketing /real estate marketing
Gambling

The usecase_summary is a free-form field with a 500-character limit. Use this field to accurately explain how your business will use messaging on this toll-free phone number. Message sample The sample message content is expected to match the use case and the business details provided in the form. Opt-in details The opt-in workflow description should briefly describe how the user will consent to receive messages. The optin_image_url field should contain a hosted image file with a screenshot of the opt-in clearly displayed on your website, an image of where opt-in is collected, or an image of the relevant opt-in practice. Opt-in can be collected in one of the following ways:

VERBAL
WEB_FORM
PAPER_FORM
VIA_TEXT
MOBILE_QR_CODE

Expected message volume The volume field should be populated with the expected monthly volume of the campaign six months from the start date and with the value closest to the following:

1,000
10,000
100,000
250,000
500,000
750,000
1,000,000
5,000,000
10,000,000+

Verification requests submitted via API will fail if a value other than the one listed above is populated in the field. Only a single value will be accepted.

What do the different statuses mean?

TF verification status	Description
SUBMITTED	The carrier has accepted the submission and is reviewing the request.
APPROVED	The request has been verified by the carrier.
REJECTED	The carrier has rejected the toll-free verification request. The use case cannot be submitted for verification anymore.
UPDATE_REQUIRED	Verification submission has been put on hold and the carrier has requested additional data to validate the request. You need to provide this additional information via the Update API request. If you do not provide details within six days from when the status is posted, the open request will be closed and the toll-free verification status will change to REJECTED.

Check the status of your toll-free verification via API. A callback with the updated status is sent to the callback_url if it is provided while submitting the request.

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

Submitting a toll-free verification request via APIs

Java

Toll-free verification status: from unverified to approved

Submitting your business details

Submitting message details

What do the different statuses mean?

​Submitting a toll-free verification request via APIs

​Java

​Toll-free verification status: from unverified to approved

​Submitting your business details

​Submitting message details

​What do the different statuses mean?

Submitting a toll-free verification request via APIs

Java

Toll-free verification status: from unverified to approved

Submitting your business details

Submitting message details

What do the different statuses mean?