Toll-free Verification

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 identifies the sender, ensures compliance with toll-free messaging best practices, and helps eliminate bad actors from the A2P channel. During verification, you provide information about your company and messaging use cases. If you’re a reseller, you must also provide information about the customers on whose behalf you will send messages.

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

API Endpoint

Base URL

https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/

Use Cases

The following use cases are supported for toll-free verification:

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

Opt-in Types

You must specify how users consent to receive messages:

Opt-in Type	Requirements
VERBAL	Include sample verbal consent collection in a document linked via `optin_image_url`
WEB_FORM	Include link to the web form in `optin_image_url`
PAPER_FORM	Include link to the paper form (can be scanned image) in `optin_image_url`
VIA_TEXT	Describe the keyword campaign in a document linked via `optin_image_url`
MOBILE_QR_CODE	Include the QR code in a document linked via `optin_image_url`

Volume Tiers

Specify your expected monthly message volume using one of these values:

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

Provide a value that accommodates projected growth for the next six to eight months.

The Verification Object

Attributes

uuid

string

The unique identifier for the verification request.

profile_uuid

string

The unique identifier of an existing Plivo profile.

number

string

The toll-free number for which verification is being initiated.

usecase

list

The messaging use case(s) for which the toll-free number will be used. One use case is mandatory; multiple use cases can be added as a list of strings.

usecase_summary

string

Explanation of how messaging will be used on this toll-free number by your business.

message_sample

string

Sample message(s) that your business will send to end users. Multiple samples are allowed.

optin_image_url

list

A valid URL where you submit images explaining the opt-in process. Multiple URLs are allowed as a list of strings.

optin_type

string

Describes how a user opts into receiving text messages.

volume

string

An estimate of the monthly volume of messages you will send from the toll-free number.

additional_information

string

Any additional information related to the website, such as terms of service or privacy policy links.

extra_data

string

Any additional information for your own internal reference.

status

string

The status of the toll-free verification request.

rejection_reason

string

The reason for toll-free verification rejection (if applicable).

callback_url

string

A valid URL where verification-related callbacks will be sent.

created

datetime

The date when the verification request was created.

last_modified

datetime

The date when the verification request was last modified.

Example Verification Object

{
  "uuid": "7f4b4d49-8d3f-422c-4f3d-5b0166223a4b",
  "profile_uuid": "bd781875-24f8-4f51-8472-85e697db24dX",
  "number": "18664892XXX",
  "usecase": "2FA",
  "usecase_summary": "We send 2FA codes to customers when they sign up.",
  "message_sample": "Your Plivo verification code is xxxx.",
  "optin_image_url": "https://abc.com/test1",
  "optin_type": "WEB_FORM",
  "volume": "1,000",
  "additional_information": "Privacy policy: https://www.plivo.com/legal/privacy/",
  "extra_data": "Ticket 1",
  "status": "SUBMITTED",
  "callback_url": "https://abc.com/test2",
  "created": "2023-11-07T14:47:00.761439Z",
  "last_modified": "2023-11-07T14:47:00.761412Z"
}

Verification Statuses

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 verification request. The use case cannot be submitted for verification anymore.
UPDATE_REQUIRED	The carrier has requested additional data to validate the request. You must provide this information via the Update API within six days, or the request will be rejected.

Create a Verification Request

Create a new toll-free verification request. You must first create a Plivo profile before starting the verification process.

POST https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/

Arguments

profile_uuid

string

required

The unique identifier of an existing Plivo profile.

number

string

required

The toll-free number in E.164 format for which verification is being initiated. Only US and Canadian toll-free numbers are accepted. Only one number per request.

usecase

string

required

The messaging use case(s). Multiple use cases can be added as a comma-separated string. Example: "2FA, CUSTOMER_CARE"

usecase_summary

string

required

Explanation of how messaging will be used (max 500 characters).

message_sample

string

required

Sample message(s) that you will send to end users (max 1000 characters).

optin_image_url

string

required

A valid URL where you submit images demonstrating the opt-in process. Multiple URLs allowed as comma-separated string.

optin_type

string

required

How users opt in to messages. Values: VERBAL, WEB_FORM, PAPER_FORM, VIA_TEXT, MOBILE_QR_CODE

volume

string

required

Expected monthly message volume. Must be one of the allowed volume tier values.

additional_information

string

Additional information such as terms of service or privacy policy links (max 500 characters).

extra_data

string

Information for your internal reference (max 100 characters).

callback_url

string

A valid URL where verification-related callbacks will be sent.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.tollfree_verification.create(
    profile_uuid="<profile_uuid>",
    number="<toll_free_number>",
    usecase="2FA",
    usecase_summary="We send 2FA codes to customers when they sign up.",
    message_sample="Your verification code is xxxx.",
    optin_image_url="https://example.com/optin",
    optin_type="WEB_FORM",
    volume="10,000"
)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.tollfreeVerification.create({
    profile_uuid: '<profile_uuid>',
    number: '<toll_free_number>',
    usecase: '2FA',
    usecase_summary: 'We send 2FA codes to customers when they sign up.',
    message_sample: 'Your verification code is xxxx.',
    optin_image_url: 'https://example.com/optin',
    optin_type: 'WEB_FORM',
    volume: '10,000'
}).then(console.log);

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/" \
    -u AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
        "profile_uuid": "<profile_uuid>",
        "number": "<toll_free_number>",
        "usecase": "2FA",
        "usecase_summary": "We send 2FA codes to customers when they sign up.",
        "message_sample": "Your verification code is xxxx.",
        "optin_image_url": "https://example.com/optin",
        "optin_type": "WEB_FORM",
        "volume": "10,000"
    }'

Response

{
  "api_id": "ffe33a14-81fc-11ee-b92a-0242ac110005",
  "message": "created",
  "uuid": "4a59de5e-204a-47e8-6973-e713f9a1e0ce"
}

Retrieve a Verification Request

Get details of a specific toll-free verification request.

GET https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/{uuid}/

Arguments

uuid

string

required

The unique identifier of the verification request.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.tollfree_verification.get('<uuid>')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.tollfreeVerification.get('<uuid>').then(console.log);

curl "https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/{uuid}/" \
    -u AUTH_ID:AUTH_TOKEN

Response

{
  "api_id": "aecbd496-81fd-11ee-b92a-0242ac110005",
  "uuid": "7f4b4d49-8d3f-422c-4f3d-5b0166223a4b",
  "profile_uuid": "bd781875-24f8-4f51-8472-85e697db24dX",
  "created": "2023-11-07T14:47:00.761439Z",
  "last_modified": "2023-11-07T14:47:00.761412Z",
  "message_sample": "Your Plivo verification code is xxxx.",
  "number": "18664892XXX",
  "optin_image_url": "https://abc.com/test1",
  "optin_type": "WEB_FORM",
  "status": "SUBMITTED",
  "usecase": "2FA",
  "usecase_summary": "We send 2FA codes to customers when they sign up.",
  "volume": "1,000",
  "additional_information": "Privacy policy: https://www.plivo.com/legal/privacy/",
  "extra_data": "Ticket 1",
  "callback_url": "https://abc.com/test2",
  "error_message": ""
}

List All Verification Requests

Get the status of all toll-free verification requests for your account.

GET https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/

Query Parameters

number

string

Filter by a single toll-free number.

status

string

Filter by verification status.

profile_uuid

string

Filter by profile UUID.

usecase

string

Filter by use case(s) in comma-separated format. This is an exact match.

created

string

Filter by creation date (YYYY-MM-DD format). Supports created__gt, created__gte, created__lt, created__lte for range queries. Default window is 7 days; maximum is 30 days.

limit

integer

Number of results per page (1-20). Default: 20.

offset

integer

Number of records to skip for pagination.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.tollfree_verification.list(limit=10, offset=0)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.tollfreeVerification.list({ limit: 10, offset: 0 }).then(console.log);

curl "https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/?limit=10" \
    -u AUTH_ID:AUTH_TOKEN

Response

{
  "api_id": "c2b5a6ec-81ff-11ee-9447-0242ac110002",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": [
    {
      "uuid": "4bfde431-5317-43cc-644a-2b41e2af4e16",
      "profile_uuid": "bd781875-24f8-4f51-8472-85e697db24d8",
      "number": "18884353XXX",
      "usecase": "ACCOUNT_NOTIFICATION",
      "usecase_summary": "We send account notifications to customers whenever they change the password.",
      "message_sample": "You have successfully updated the password for the Plivo account.",
      "optin_image_url": "https://abc.com/test4",
      "optin_type": "WEB_FORM",
      "volume": "10,000",
      "status": "SUBMITTED",
      "additional_information": "Privacy policy: https://www.plivo.com/legal/privacy/",
      "callback_url": "https://abc.com/test3",
      "created": "2023-11-13T08:35:46.024584Z",
      "last_modified": "2023-11-13T08:35:46.024543Z"
    }
  ]
}

Update a Verification Request

Update an existing toll-free verification request. Only requests with status SUBMITTED or UPDATE_REQUIRED can be updated.

POST https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/{uuid}/

Arguments

uuid

string

required

The unique identifier of the verification request.

profile_uuid

string

The unique identifier of an existing Plivo profile.

usecase

string

The messaging use case(s) in comma-separated format.

usecase_summary

string

Explanation of how messaging will be used (max 500 characters).

message_sample

string

Sample message(s) that you will send (max 1000 characters).

optin_image_url

string

A valid URL demonstrating the opt-in process.

optin_type

string

How users opt in to messages. Values: VERBAL, WEB_FORM, PAPER_FORM, VIA_TEXT, MOBILE_QR_CODE

volume

string

Expected monthly message volume.

additional_information

string

Additional information (max 500 characters).

extra_data

string

Information for your internal reference.

callback_url

string

A valid URL for verification callbacks.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.tollfree_verification.update(
    '<uuid>',
    usecase_summary="Updated summary for our 2FA use case."
)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.tollfreeVerification.update('<uuid>', {
    usecase_summary: 'Updated summary for our 2FA use case.'
}).then(console.log);

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/{uuid}/" \
    -u AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"usecase_summary": "Updated summary for our 2FA use case."}'

Response

{
  "api_id": "c74aa53a-8200-11ee-b92a-0242ac110005",
  "message": "Tollfree verification request for uuid 4bfde431-5317-43cc-644a-2b41e2af4e16 updated successfully."
}

Delete a Verification Request

Delete an existing verification request. Only requests with status SUBMITTED, PROCESSING, or UPDATE_REQUIRED can be deleted.

DELETE https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/{uuid}/

Arguments

uuid

string

required

The unique identifier of the verification request to delete.

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.tollfree_verification.delete('<uuid>')
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.tollfreeVerification.delete('<uuid>').then(console.log);

curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/{uuid}/" \
    -u AUTH_ID:AUTH_TOKEN

Callbacks

A callback is sent to the callback_url (if specified) whenever the verification status changes:

From SUBMITTED to APPROVED, REJECTED, or UPDATE_REQUIRED
From UPDATE_REQUIRED to APPROVED or REJECTED

Callback Parameters

uuid

string

The unique identifier of the verification request.

number

string

The toll-free number associated with the verification request.

status

string

The current status of the verification request.

error_message

string

Error or rejection reason (if applicable).

Example Callback Payload

{
  "uuid": "7f4b4d49-8d3f-422c-4f3d-5b0166223a4b",
  "number": "18664892XXX",
  "status": "APPROVED",
  "error_message": ""
}

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

Toll-free Verification

API Endpoint

Use Cases

Opt-in Types

Volume Tiers

The Verification Object

Attributes

Example Verification Object

Verification Statuses

Create a Verification Request

Arguments

Response

Retrieve a Verification Request

Arguments

Response

List All Verification Requests

Query Parameters

Response

Update a Verification Request

Arguments

Response

Delete a Verification Request

Arguments

Callbacks

Callback Parameters

Example Callback Payload

​API Endpoint

​Use Cases

​Opt-in Types

​Volume Tiers

​The Verification Object

​Attributes

​Example Verification Object

​Verification Statuses

​Create a Verification Request

​Arguments

​Response

​Retrieve a Verification Request

​Arguments

​Response

​List All Verification Requests

​Query Parameters

​Response

​Update a Verification Request

​Arguments

​Response

​Delete a Verification Request

​Arguments

​Callbacks

​Callback Parameters

​Example Callback Payload

API Endpoint

Use Cases

Opt-in Types

Volume Tiers

The Verification Object

Attributes

Example Verification Object

Verification Statuses

Create a Verification Request

Arguments

Response

Retrieve a Verification Request

Arguments

Response

List All Verification Requests

Query Parameters

Response

Update a Verification Request

Arguments

Response

Delete a Verification Request

Arguments

Callbacks

Callback Parameters

Example Callback Payload