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.
Here’s how to use Plivo’s APIs to submit a verification request for your existing SMS-enabled toll-free numbers.
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 Python development environment.
1
2
3
4
5
6
7
8
9
10
11
12
13
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.tollfree_verification.create(
profile_uuid="<Your Plivo profile_uuid>",
usecase="<Your use case from the list of allowed use cases>",
usecase_summary="<A summary of your use case>",
message_sample="<Your message sample>",
optin_image_url="<A valid optin image url>",
optin_type="<One of the allowed optin type>",
volume="<The volume of message from one of the allowed values>",
number="<Your US/CA Plivo toll-free number>")
print(response)
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 PHP 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
<?php
require 'vendor/autoload.php';
use Plivo\RestClient;
use Plivo\Exceptions\PlivoRestException;
$client = new RestClient("<auth_id>","<auth_token>");
try {
$response = $client->tollfreeVerification->create(
"<Your US/CA Plivo toll-free number>",
"<Your use case from the list of allowed use cases>",
"<A summary of your use case>",
"<Your Plivo profile_uuid>",
"<One of the allowed optin type>",
"<The volume of message from one of the allowed values>",
"<Your message sample>",
"<A valid optin image url>"
);
print_r($response);
}
catch (PlivoRestException $ex) {
print_r($ex);
}
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 Node.js development environment.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
var plivo = require('plivo');
(function main() {
'use strict';
var client = new plivo.Client("<auth_id>", "<auth_token>");
client.tollfreeVerification.create(
message_sample: "<Your message sample>",
number: "<Your US/CA Plivo toll-free number>",
optin_image_url: "<A valid optin image url>",
optin_type: "<One of the allowed optin type>",
profile_uuid: "<Your Plivo profile_uuid>",
usecase: "<Your use case from the list of allowed use cases>",
usecase_summary: "<A summary of your use case>",
volume: "<The volume of message from one of the allowed values>"
).then(function(response) {
console.log(response);
}, function(err) {
console.error(err);
});
})();
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 Ruby 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
require 'rubygems'
require 'plivo'
include Plivo
include Plivo::Exceptions
api = RestClient.new("<auth_id>", "<auth_token>")
begin
response = api.tollfree_verifications.create(
'<Your US/CA Plivo toll-free number>',
'<Your use case from the list of allowed use cases>',
'<Your message sample>',
'<Your Plivo profile_uuid>',
'<One of the allowed optin type>',
'<A valid optin image url>',
'<The volume of message from one of the allowed values>',
'<A summary of your use case>'
)
puts response
rescue PlivoRESTError => e
puts 'Exception: ' + e.message
end
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.
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
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();
}
}
}
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)
}
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 .NET 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
32
33
34
using System;
using System.Collections.Generic;
using Plivo;
using Plivo.Exception;
namespace PlivoExamples
{
internal class Program
{
public static void Main(string[] args)
{
var api = new PlivoApi("<auth_id>","<auth_token>");
try
{
var response = api.TollfreeVerification.Create(
"<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>",
"<Your message sample>",
"<A valid optin image url>",
"<One of the allowed optin type>",
"<The volume of message from one of the allowed values>"
);
Console.WriteLine(response);
}
catch (Exception e)
{
Console.WriteLine("Exception: " + e.Message);
}
}
}
}
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.
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
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:
Then, per the diagram above, For Client A, Ovilp must:
For Client B, Ovilp must:
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.
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:
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:
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.
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. </br></br>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.