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
10
100
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.

Both comma-separated and plain integer formats are accepted — "1,000" and "1000" are equivalent. Responses return the plain form. The highest tier must include the + sign: "10,000,000+" is accepted, "10,000,000" without the plus is rejected.

The Verification Object

Field presence in responses. The two read endpoints handle empty fields differently. Retrieve omits fields that have no value. List returns every field, using an empty string ("") for fields with no value. When reading a single record, treat all optional fields as possibly absent and use safe key access.

Attributes

string

The unique identifier for the verification request.

string

The unique identifier of an existing Plivo profile.

string

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

string

The messaging use case(s) for which the toll-free number will be used. One use case is mandatory. Multiple use cases are supplied as a comma-separated string, not an array — for example "2FA,ACCOUNT_NOTIFICATION".

string

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

string

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

string

A valid URL where you submit images explaining the opt-in process. Multiple URLs are supplied as a comma-separated string, not an array.

string

Describes how a user opts into receiving text messages.

string

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

string

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

string

Public URL to the brand’s terms and conditions page.

string

Public URL to the brand’s privacy policy page.

string

Confirmation message sent to a subscriber after they opt in.

string

Response sent when a subscriber messages the HELP keyword.

string

Any additional information for your own internal reference.

string

The status of the toll-free verification request.

string

The reason a verification request was rejected or requires an update. Present in Retrieve only when the request has an error state; returned as an empty string in List when there is no error. This value can change as upstream feedback arrives, so don’t treat it as stable.

string

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

string

default:"POST"

The HTTP method used to invoke callback_url. Allowed values: GET, POST. The default applies only when a callback_url is configured; if no callback URL is set, this field is empty.

datetime

The date when the verification request was created.

datetime

The date when the verification request was last modified.

Example Verification Object

{
  "uuid": "7f4b4d49-8d3f-422c-4f3d-5b0166223a4b",
  "profile_uuid": "766e31a9-b81e-4842-9b91-78b444bf07XX",
  "number": "18004097XXX",
  "usecase": "2FA",
  "usecase_summary": "We send two-factor authentication codes to customers when they sign in.",
  "message_sample": "Your verification code is 123456. Reply STOP to opt out.",
  "optin_image_url": "https://example.com/optin.png",
  "optin_type": "WEB_FORM",
  "volume": "1000",
  "additional_information": "Additional information about the brand website and compliance.",
  "terms_and_conditions_link": "https://example.com/terms",
  "privacy_policy_link": "https://example.com/privacy",
  "optin_message": "Thank you for subscribing. Reply HELP for help, STOP to unsubscribe.",
  "help_message": "For help contact support@example.com. Reply STOP to unsubscribe.",
  "extra_data": "Ticket 1",
  "status": "SUBMITTED",
  "callback_url": "https://example.com/callback",
  "callback_method": "POST",
  "created": "2026-09-03T06:18:26.855298Z",
  "last_modified": "2026-09-03T06:18:26.855270Z"
}

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.

terms_and_conditions_link and privacy_policy_link are required from September 15, 2026.If you already send toll-free verification requests, add both fields before that date. The API accepts requests without them until September 15, 2026 and rejects them from that date onward. The Plivo console has required both since September 7, 2026.Both URLs must be publicly accessible and carry specific SMS disclosures — see Toll-free registration guidelines for what each page has to contain.

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

Arguments

string

required

The unique identifier of an existing Plivo profile.

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.

string

required

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

string

required

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

string

required

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

string

required

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

string

required

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

string

required

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

string

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

string

required

Public URL to the brand’s terms and conditions page. Enforced from September 15, 2026 — see the note above.

string

required

Public URL to the brand’s privacy policy page. Enforced from September 15, 2026 — see the note above.

string

Confirmation message sent to a subscriber after they opt in (max 500 characters).

string

Response sent when a subscriber messages the HELP keyword (max 500 characters).

string

Information for your internal reference (max 100 characters).

string

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

string

default:"POST"

The HTTP method used to invoke callback_url. Allowed values: GET, POST.

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

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": "4da14842-a75f-11f1-8a0f-0242ac110004",
  "uuid": "7994b5ad-939e-4dd5-74ac-ee464604eb8b",
  "profile_uuid": "766e31a9-b81e-4842-9b91-78b444bf07XX",
  "number": "18004097XXX",
  "usecase": "2FA",
  "usecase_summary": "We send two-factor authentication codes to customers when they sign in.",
  "message_sample": "Your verification code is 123456. Reply STOP to opt out.",
  "optin_image_url": "https://example.com/optin.png",
  "optin_type": "WEB_FORM",
  "volume": "1000",
  "additional_information": "Additional information about the brand website and compliance.",
  "terms_and_conditions_link": "https://example.com/terms",
  "privacy_policy_link": "https://example.com/privacy",
  "optin_message": "Thank you for subscribing. Reply HELP for help, STOP to unsubscribe.",
  "help_message": "For help contact support@example.com. Reply STOP to unsubscribe.",
  "callback_url": "https://example.com/callback",
  "callback_method": "POST",
  "status": "SUBMITTED",
  "created": "2026-09-03T06:18:26.855298Z",
  "last_modified": "2026-09-03T06:18:26.855270Z"
}

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

string

Filter by a single toll-free number.

string

Filter by verification status.

string

Filter by profile UUID.

string

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

string

Filter by creation date (YYYY-MM-DD format). Use the suffixed forms only — created__gte and created__lte are inclusive, created__gt and created__lt are exclusive. A bare created= value is not supported and returns no results. The span between created__gte and created__lte can be up to 2 years, and created__gte must be within the last 2 years. See the date filtering note below.

integer

Number of results per page. Maximum and default are both 20. Values above 20 are silently reduced to 20 rather than rejected — check meta.limit in the response to confirm the value applied.

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

Date filtering behaviourIf you pass no date filter, only records created in the last 7 days are returned.If you pass only one bound, a 7-day window is applied around it:

created__gte=X returns records from X through X+6 days
created__lte=Y returns records from Y-6 days through Y

To search a wider range you must pass both created__gte and created__lte. The span between them can be up to 2 years.Records older than 2 years can’t be listed. Retrieve them directly by UUID instead — the Retrieve endpoint has no age limit.

Response

{
  "api_id": "c2b5a6ec-81ff-11ee-9447-0242ac110002",
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 1
  },
  "objects": [
    {
      "uuid": "7994b5ad-939e-4dd5-74ac-ee464604eb8b",
      "profile_uuid": "766e31a9-b81e-4842-9b91-78b444bf07XX",
      "number": "18004097XXX",
      "usecase": "2FA",
      "usecase_summary": "We send two-factor authentication codes to customers when they sign in.",
      "message_sample": "Your verification code is 123456. Reply STOP to opt out.",
      "optin_image_url": "https://example.com/optin.png",
      "optin_type": "WEB_FORM",
      "volume": "1000",
      "additional_information": "Additional information about the brand website and compliance.",
      "terms_and_conditions_link": "https://example.com/terms",
      "privacy_policy_link": "https://example.com/privacy",
      "optin_message": "Thank you for subscribing. Reply HELP for help, STOP to unsubscribe.",
      "help_message": "For help contact support@example.com. Reply STOP to unsubscribe.",
      "callback_url": "https://example.com/callback",
      "callback_method": "POST",
      "error_message": "",
      "extra_data": "",
      "status": "SUBMITTED",
      "created": "2026-09-03T06:18:26.855298Z",
      "last_modified": "2026-09-03T06:18:26.855270Z"
    }
  ]
}

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

string

required

The unique identifier of the verification request.

string

The unique identifier of an existing Plivo profile.

string

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

string

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

string

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

string

A valid URL demonstrating the opt-in process.

string

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

string

Expected monthly message volume.

string

Additional information (max 1000 characters).

string

Public URL to the brand’s terms and conditions page. Required on submissions from September 15, 2026.

string

Public URL to the brand’s privacy policy page. Required on submissions from September 15, 2026.

string

Confirmation message sent to a subscriber after they opt in (max 500 characters).

string

Response sent when a subscriber messages the HELP keyword (max 500 characters).

string

Information for your internal reference.

string

A valid URL for verification callbacks.

string

default:"POST"

The HTTP method used to invoke callback_url. Allowed values: GET, POST.

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

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

Response

On success the API returns HTTP 204 No Content with an empty body. To confirm the deletion, call the Retrieve endpoint with the same UUID. It returns HTTP 404:

{
  "error": "not found"
}

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

string

The unique identifier of the verification request.

string

The toll-free number associated with the verification request.

string

The current status of the verification request.

string

Error or rejection reason (if applicable).

Example Callback Payload

{
  "uuid": "7994b5ad-939e-4dd5-74ac-ee464604eb8b",
  "number": "18004097XXX",
  "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

Response

Callbacks

Callback Parameters

Example Callback Payload