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

# US toll-free verification

> Verify a US toll-free (8XX) messaging number through the Vobiz Messaging API - submit the business and use-case details, attach the number, poll the review, and appeal a rejection. No brand record is needed.

US toll-free numbers (area codes 800, 833, 844, 855, 866, 877 and 888) carry A2P messages after a one-time **verification**. The verification describes your business and your messaging program in a single submission. Unlike [10DLC](/docs/sms/compliance/us-10dlc-campaigns), it does not require a brand record first.

<Tip>
  Building with code? Submit verification with [Create a toll-free verification request](/docs/sms/api/10dlc/create-toll-free-campaign) in the [Messaging API](/docs/sms/overview).
</Tip>

In the console, toll-free verifications live under **SMS & RCS → Registration → Toll-free**. This page covers the same flow through the API.

<Note>
  Until the verification is approved, messages from the toll-free number fail with a carrier error such as `EC_TF_NUMBER_NOT_VERIFIED` in the message's `errorCode`.
</Note>

## Verification fields

Send these on [`POST /10dlc/campaigns/toll-free`](/docs/sms/api/10dlc/create-toll-free-campaign). There is no `brandId`; the business details are part of this request.

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Internal name for the verification. |
| `referenceId` | string | no | Your idempotency reference. A retry with the same value reconciles to the same record. |
| `numbers` | string\[] | | Toll-free numbers to verify, in E.164 format, for example `+18335550100`. |
| `numberKeys` | string\[] | | Alternative to `numbers`: the `numberKey` values from [`GET /numbers/available`](/docs/sms/api/numbers/search-available-numbers). |
| `useCase` | string | | The messaging use case. See [values](#registry-values). |
| `messageVolume` | string | | Expected messages per month. See [values](#registry-values). |
| `programSummary` | string | | What you send, to whom, and how they opt in. |
| `exampleMessage` | string | | One representative message. Start with the business name and include opt-out language. Note the singular field name. |
| `optIns` | object | | How consent is collected, in the registry's structure, for example `{"web": {"url": "...", "callToAction": "..."}}`. |
| `optInImageURLs` | string\[] | | Public URLs of screenshots that show the opt-in form or flow. |
| `additionalInformation` | string | | Anything the reviewer should know. |
| `privacyPolicyUrl` | string | | Public privacy policy. |
| `termsAndConditionsUrl` | string | | Public terms page. |
| `businessName` | string | | Business name as customers know it. |
| `legalName` | string | | Registered legal name. |
| `businessDBA` | string | | Trading name if different. Note the casing: `businessDBA` here, `businessDba` on a [brand](/docs/sms/compliance/us-10dlc-brands). |
| `businessWebsite` | string | | Public website. |
| `countryCode` | string | | ISO 3166-1 alpha-2 country of registration. |
| `address` | object | | Registered address: `street`, `city`, `state`, `zipCode`. |
| `taxId` | string | | EIN or equivalent registration number. |
| `taxIdIssuingCountry` | string | | ISO 3166-1 alpha-2 code of the issuing country. |
| `legalEntityType` | string | | `PRIVATE_COMPANY`, `PUBLIC_COMPANY`, `NON_PROFIT`, `GOVERNMENT` or `SOLE_PROPRIETOR`. |
| `businessRegistrationType` | string | | For non-US entities: `VAT`, `CBN`, `PROVINCIAL_NUMBER`, `ABN`, `SIREN`, `NZBN`, `CIF`, `CNPJ` or `OTHER`. |
| `businessContactFirstName` | string | | Contact person's first name. |
| `businessContactLastName` | string | | Contact person's last name. |
| `supportPhone` | string | | Support phone in E.164 format. |
| `supportEmail` | string | | Support mailbox. |
| `customerCareEmail` | string | | Mailbox shown to recipients who ask for help. |
| `campaignVerifyToken` | string | | Verification token, where the registry has issued one for your program. |
| `priorityId` | string (UUID) | | A registration priority from [`GET /10dlc/campaigns/priorities`](/docs/sms/api/10dlc/campaign-priorities). Non-UUID values return `400 {"error": "invalid request: priorityId must be a UUID"}`. |

Any `type` you send is ignored. The resulting record always has `campaignType: TOLL_FREE_UNIFIED_NUMBER`.

### Registry values

The registry accepts these values. Vobiz passes them through as you send them.

<AccordionGroup>
  <Accordion title="useCase">
    `TWO_FACTOR_AUTH`, `NOTIFICATIONS`, `SYSTEM_ALERTS`, `APP_NOTIFICATIONS`, `BANKING`, `BOOKING_CONFIRMATIONS`, `CHATBOT`, `COURIER_SERVICES_DELIVERIES`, `EMERGENCY_ALERTS`, `EVENTS_PLANNING`, `FRAUD_ALERTS`, `GENERAL_MARKETING`, `HEALTHCARE`, `INSURANCE_SERVICES`, `LEGAL_SERVICES`, `MOTIVATIONAL_REMINDERS`, `POLITICAL`, `REAL_ESTATE_SERVICES`, `RELIGIOUS_SERVICES`, `REWARDS_PROGRAM`, `WEBINAR_REMINDERS`, `AUCTIONS`, `COVID_19_ALERTS`
  </Accordion>

  <Accordion title="messageVolume (messages per month)">
    `HUNDRED`, `TEN_THOUSAND`, `TWO_HUNDRED_FIFTY_THOUSAND`, `SEVEN_HUNDRED_FIFTY_THOUSAND`, `FIVE_MILLION`
  </Accordion>
</AccordionGroup>

## Verify a toll-free number

<Steps>
  <Step title="Buy or bring the toll-free number">
    Search with `country=US` on [`GET /numbers/available`](/docs/sms/api/numbers/search-available-numbers) and purchase with [`POST /numbers/purchase`](/docs/sms/api/numbers/purchase-number), or use a toll-free number already on your account. See the [Numbers guide](/docs/sms/numbers).
  </Step>

  <Step title="Submit the verification">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.vobiz.ai/api/v1/sms/10dlc/campaigns/toll-free" \
        -H "X-Auth-ID: MA_XXXXXXXX" \
        -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Acme toll-free notifications",
          "numbers": ["+18335550100"],
          "useCase": "NOTIFICATIONS",
          "messageVolume": "TEN_THOUSAND",
          "businessName": "Acme",
          "legalName": "Acme Corporation",
          "businessWebsite": "https://example.com",
          "countryCode": "US",
          "address": {"street": "100 Market Street", "city": "San Francisco", "state": "CA", "zipCode": "94105"},
          "taxId": "12-3456789",
          "taxIdIssuingCountry": "US",
          "legalEntityType": "PRIVATE_COMPANY",
          "businessContactFirstName": "Jane",
          "businessContactLastName": "Doe",
          "supportPhone": "+14155550100",
          "supportEmail": "support@example.com",
          "customerCareEmail": "support@example.com",
          "programSummary": "Acme sends order and shipping notifications to customers who opt in at checkout on example.com. Message frequency varies. Reply STOP to opt out, HELP for help.",
          "exampleMessage": "Acme: Your order #4821 has shipped. Track it at https://example.com/orders. Reply STOP to opt out, HELP for help.",
          "optIns": {"web": {"url": "https://example.com/checkout", "callToAction": "By checking this box you agree to receive order updates from Acme by SMS. Msg & data rates may apply. Reply STOP to opt out."}},
          "optInImageURLs": ["https://example.com/compliance/checkout-opt-in.png"],
          "privacyPolicyUrl": "https://example.com/privacy",
          "termsAndConditionsUrl": "https://example.com/terms"
        }'
      ```

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

      BASE = "https://api.vobiz.ai/api/v1/sms"
      HEADERS = {
          "X-Auth-ID": "MA_XXXXXXXX",
          "X-Auth-Token": "YOUR_AUTH_TOKEN",
          "Content-Type": "application/json",
      }

      verification = {
          "name": "Acme toll-free notifications",
          "numbers": ["+18335550100"],
          "useCase": "NOTIFICATIONS",
          "messageVolume": "TEN_THOUSAND",
          "businessName": "Acme",
          "legalName": "Acme Corporation",
          "businessWebsite": "https://example.com",
          "countryCode": "US",
          "address": {"street": "100 Market Street", "city": "San Francisco", "state": "CA", "zipCode": "94105"},
          "taxId": "12-3456789",
          "taxIdIssuingCountry": "US",
          "legalEntityType": "PRIVATE_COMPANY",
          "businessContactFirstName": "Jane",
          "businessContactLastName": "Doe",
          "supportPhone": "+14155550100",
          "supportEmail": "support@example.com",
          "customerCareEmail": "support@example.com",
          "programSummary": "Acme sends order and shipping notifications to customers who opt in at checkout on example.com. Message frequency varies. Reply STOP to opt out, HELP for help.",
          "exampleMessage": "Acme: Your order #4821 has shipped. Track it at https://example.com/orders. Reply STOP to opt out, HELP for help.",
          "optIns": {"web": {"url": "https://example.com/checkout", "callToAction": "By checking this box you agree to receive order updates from Acme by SMS. Msg & data rates may apply. Reply STOP to opt out."}},
          "optInImageURLs": ["https://example.com/compliance/checkout-opt-in.png"],
          "privacyPolicyUrl": "https://example.com/privacy",
          "termsAndConditionsUrl": "https://example.com/terms",
      }

      r = requests.post(f"{BASE}/10dlc/campaigns/toll-free", headers=HEADERS, json=verification)
      r.raise_for_status()
      print(r.json()["id"], r.json()["campaignType"], r.json()["stage"])
      ```

      ```javascript Node theme={null}
      const BASE = "https://api.vobiz.ai/api/v1/sms";
      const headers = {
        "X-Auth-ID": "MA_XXXXXXXX",
        "X-Auth-Token": "YOUR_AUTH_TOKEN",
        "Content-Type": "application/json",
      };

      const verification = {
        name: "Acme toll-free notifications",
        numbers: ["+18335550100"],
        useCase: "NOTIFICATIONS",
        messageVolume: "TEN_THOUSAND",
        businessName: "Acme",
        legalName: "Acme Corporation",
        businessWebsite: "https://example.com",
        countryCode: "US",
        address: { street: "100 Market Street", city: "San Francisco", state: "CA", zipCode: "94105" },
        taxId: "12-3456789",
        taxIdIssuingCountry: "US",
        legalEntityType: "PRIVATE_COMPANY",
        businessContactFirstName: "Jane",
        businessContactLastName: "Doe",
        supportPhone: "+14155550100",
        supportEmail: "support@example.com",
        customerCareEmail: "support@example.com",
        programSummary: "Acme sends order and shipping notifications to customers who opt in at checkout on example.com. Message frequency varies. Reply STOP to opt out, HELP for help.",
        exampleMessage: "Acme: Your order #4821 has shipped. Track it at https://example.com/orders. Reply STOP to opt out, HELP for help.",
        optIns: { web: { url: "https://example.com/checkout", callToAction: "By checking this box you agree to receive order updates from Acme by SMS. Msg & data rates may apply. Reply STOP to opt out." } },
        optInImageURLs: ["https://example.com/compliance/checkout-opt-in.png"],
        privacyPolicyUrl: "https://example.com/privacy",
        termsAndConditionsUrl: "https://example.com/terms",
      };

      const res = await fetch(`${BASE}/10dlc/campaigns/toll-free`, {
        method: "POST",
        headers,
        body: JSON.stringify(verification),
      });
      if (!res.ok) throw new Error(await res.text());
      const created = await res.json();
      console.log(created.id, created.campaignType, created.stage);
      ```
    </CodeGroup>

    The response is `201` with a [campaign object](/docs/sms/compliance/us-10dlc-campaigns#the-campaign-object) whose `campaignType` is `TOLL_FREE_UNIFIED_NUMBER` and which has no `brandId`.
  </Step>

  <Step title="Register and poll">
    From here the record behaves like any campaign:

    * [`POST /10dlc/campaigns/{id}/register`](/docs/sms/api/10dlc/register-campaign) submits it, optionally with `{"priorityId": "<uuid>"}`.
    * [`GET /10dlc/campaigns/{id}`](/docs/sms/api/10dlc/get-campaign) refreshes `stage` and `rejectionReasons`.
    * [`GET /10dlc/campaigns/{id}/network-statuses`](/docs/sms/api/10dlc/campaign-network-statuses) shows the carriers' states.
    * The `10dlc.campaign.updated` [WebSocket](/docs/sms/websocket) event fires on every change.
  </Step>

  <Step title="Handle a rejection">
    Read `rejectionReasons.rejectionDetails` on the campaign. Correct the details and submit a new verification, or [`POST /10dlc/campaigns/{id}/appeal`](/docs/sms/api/10dlc/appeal-campaign) with `{"reason": "..."}` explaining what you fixed. Toll-free records are not edited through `PUT /10dlc/campaigns/{id}`; that endpoint returns `400 {"error": "invalid request: toll-free campaigns cannot be updated through this endpoint"}` for them.
  </Step>

  <Step title="Send">
    When `stage` is `REGISTERED`, send with the toll-free number as `from` on [`POST /messages`](/docs/sms/api/messages/send-message).
  </Step>
</Steps>

## How toll-free numbers appear on your account

On [`GET /numbers`](/docs/sms/api/numbers/list-numbers) a toll-free number has `tollFree: true` and `registration.kind: toll_free`:

```json theme={null}
{
  "e164": "+18335550100",
  "countryCode": "US",
  "channels": ["sms", "mms"],
  "tollFree": true,
  "tenDlc": {
    "campaignId": "a1f0c2d3-4e5b-4c6d-8e7f-9a0b1c2d3e4f",
    "campaignName": "Acme toll-free notifications",
    "stage": "REGISTERED"
  },
  "registration": {
    "kind": "toll_free",
    "status": "approved",
    "campaignId": "a1f0c2d3-4e5b-4c6d-8e7f-9a0b1c2d3e4f",
    "campaignName": "Acme toll-free notifications",
    "stage": "REGISTERED"
  }
}
```

`registration.status` follows the same values as for 10DLC: `not_registered`, `draft`, `pending`, `approved`, `rejected`. See the [compliance overview](/docs/sms/compliance/overview#tracking-status).

## Common toll-free rejections

* **Opt-in not demonstrated.** Add screenshots to `optInImageURLs` and spell out the consent text in `optIns.callToAction`.
* **Example message missing brand or STOP.** Start `exampleMessage` with the business name and end it with opt-out instructions.
* **Website or policy mismatch.** `businessWebsite`, `privacyPolicyUrl` and `termsAndConditionsUrl` must be live and belong to the same business as `legalName`.
* **Use case does not match the summary.** Pick the `useCase` that describes the actual content, and keep `programSummary` consistent with it.

## Next steps

<CardGroup cols={2}>
  <Card title="10DLC campaigns" icon="bullhorn" href="/docs/sms/compliance/us-10dlc-campaigns">
    The flow for US local numbers.
  </Card>

  <Card title="Toll-free endpoint" icon="code" href="/docs/sms/api/10dlc/create-toll-free-campaign">
    Full request and response schema.
  </Card>
</CardGroup>

## Build it with the Messaging API

<CardGroup cols={2}>
  <Card title="Toll-free endpoint" icon="code" href="/docs/sms/api/10dlc/create-toll-free-campaign">
    Submit a verification request by API.
  </Card>

  <Card title="WebSocket events" icon="bolt" href="/docs/sms/websocket">
    Follow review status live.
  </Card>

  <Card title="Sending SMS" icon="message" href="/docs/sms/channels/sms">
    Send from your verified toll-free number.
  </Card>

  <Card title="Messaging webhooks" icon="webhook" href="/docs/sms/webhooks">
    Track delivery once traffic flows.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.