> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Toll-free Verification

> Verify toll-free numbers for US A2P messaging

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.

> [!NOTE]
>
> 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

```text Base URL theme={null}
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+ |

> [!NOTE]
>
> Provide a value that accommodates projected growth for the next six to eight months.

> [!NOTE]
>
> 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

> [!NOTE]
>
> **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

**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** `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"`.

**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** `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.

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

**terms\_and\_conditions\_link** `string`

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

**privacy\_policy\_link** `string`

Public URL to the brand's privacy policy page.

**optin\_message** `string`

Confirmation message sent to a subscriber after they opt in.

**help\_message** `string`

Response sent when a subscriber messages the HELP keyword.

**extra\_data** `string`

Any additional information for your own internal reference.

**status** `string`

The status of the toll-free verification request.

**error\_message** `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.

**callback\_url** `string`

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

**callback\_method** `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.

**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

```json theme={null}
{
  "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](https://plivo.com/docs/messaging/api/10dlc/profile.md) before starting the verification process.

> [!WARNING]
>
> **`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](https://plivo.com/docs/messaging/concepts/toll-free-registration-guidelines.md) for what each page has to contain.

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

### Arguments

**profile\_uuid** `string` *required*

The unique identifier of an existing [Plivo profile](https://plivo.com/docs/messaging/api/10dlc/profile.md).

**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 1000 characters).

**terms\_and\_conditions\_link** `string` *required*

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

**privacy\_policy\_link** `string` *required*

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

**optin\_message** `string`

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

**help\_message** `string`

Response sent when a subscriber messages the HELP keyword (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.

**callback\_method** `string` (default: POST)

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

```python Python theme={null}
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)
```

```javascript Node.js theme={null}
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);
```

```bash cURL theme={null}
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

```json theme={null}
{
  "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.

```python Python theme={null}
import plivo

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

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

```javascript Node.js theme={null}
const plivo = require('plivo');

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

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

```bash cURL theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/TollfreeVerification/{uuid}/" \
    -u AUTH_ID:AUTH_TOKEN
```

### Response

```json theme={null}
{
  "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

**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\_\_gt, created\_\_gte, created\_\_lt, created\_\_lte** `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.

**limit** `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.

**offset** `integer`

Number of records to skip for pagination.

```python Python theme={null}
import plivo

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

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

```javascript Node.js theme={null}
const plivo = require('plivo');

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

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

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

> [!WARNING]
>
> **Date filtering behaviour**
>
> If 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

```json theme={null}
{
  "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

**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 1000 characters).

**terms\_and\_conditions\_link** `string`

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

**privacy\_policy\_link** `string`

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

**optin\_message** `string`

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

**help\_message** `string`

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

**extra\_data** `string`

Information for your internal reference.

**callback\_url** `string`

A valid URL for verification callbacks.

**callback\_method** `string` (default: POST)

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

```python Python theme={null}
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)
```

```javascript Node.js theme={null}
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);
```

```bash cURL theme={null}
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

```json theme={null}
{
  "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.

```python Python theme={null}
import plivo

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

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

```javascript Node.js theme={null}
const plivo = require('plivo');

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

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

```bash cURL theme={null}
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:

```json theme={null}
{
  "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

**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

```json theme={null}
{
  "uuid": "7994b5ad-939e-4dd5-74ac-ee464604eb8b",
  "number": "18004097XXX",
  "status": "APPROVED",
  "error_message": ""
}
```