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.

Go

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’s APIs, follow our instructions to set up a Go development environment.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
package main

import (
    "fmt"
    "github.com/plivo/plivo-go/v7"
)

func main() {
    client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    if err != nil {
        fmt.Print("Error", err.Error())
        return
    }
    response, err := client.TollFreeRequestVerification.Create(
        plivo.TollfreeVerificationCreateParams{
            Number:         "<Your US/CA Plivo toll-free number>",
            ProfileUUID:    "<Your Plivo profile_uuid>",
            Usecase:        "<Your use case from the list of allowed use cases>",
            UsecaseSummary: "<A summary of your use case>",
            Volume:         "<The volume of message from one of the allowed values>",
            MessageSample:  "<Your message sample>",
            OptInImageURL:  "<A valid optin image url>",
            OptInType:      "<One of the allowed optin type>",
        })

    if err != nil {
        fmt.Print("Error", err.Error())
        return
    }
    fmt.Printf("Response: %+v\n", response)
}

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.

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.

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

1. 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.
2. 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.
3. Content related to SHAFT (sex, hate, alcohol, firearms, and tobacco)
4. Cannabis promotion/sale
5. Debt relief
6. High-risk financial services
7. Third-party lead generation services
8. Affiliate marketing /real estate marketing
9. 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?

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.