US toll-free verification

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, it does not require a brand record first.

Building with code? Submit verification with Create a toll-free verification request in the Messaging API.

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

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.

Verification fields

Send these on POST /10dlc/campaigns/toll-free. 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`.
`useCase`	string		The messaging use case. See values.
`messageVolume`	string		Expected messages per month. See 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.
`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`. 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.

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

messageVolume (messages per month)

HUNDRED, TEN_THOUSAND, TWO_HUNDRED_FIFTY_THOUSAND, SEVEN_HUNDRED_FIFTY_THOUSAND, FIVE_MILLION

Verify a toll-free number

Buy or bring the toll-free number

Search with country=US on GET /numbers/available and purchase with POST /numbers/purchase, or use a toll-free number already on your account. See the Numbers guide.

Submit the verification

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"
  }'

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"])

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);

The response is 201 with a campaign object whose campaignType is TOLL_FREE_UNIFIED_NUMBER and which has no brandId.

From here the record behaves like any campaign:

POST /10dlc/campaigns/{id}/register submits it, optionally with {"priorityId": "<uuid>"}.
GET /10dlc/campaigns/{id} refreshes stage and rejectionReasons.
GET /10dlc/campaigns/{id}/network-statuses shows the carriers’ states.
The 10dlc.campaign.updated WebSocket event fires on every change.

Handle a rejection

Read rejectionReasons.rejectionDetails on the campaign. Correct the details and submit a new verification, or POST /10dlc/campaigns/{id}/appeal 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.

Send

When stage is REGISTERED, send with the toll-free number as from on POST /messages.

How toll-free numbers appear on your account

On GET /numbers a toll-free number has tollFree: true and registration.kind: toll_free:

{
  "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.

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

10DLC campaigns

The flow for US local numbers.

Toll-free endpoint

Full request and response schema.

Build it with the Messaging API

Toll-free endpoint

Submit a verification request by API.

WebSocket events

Follow review status live.

Sending SMS

Send from your verified toll-free number.

Messaging webhooks

Track delivery once traffic flows.

Getting Started

Using Vobiz Platform

Messaging (SMS & RCS)

Compliance (India)

Tools

US toll-free verification

Verification fields

Registry values

Verify a toll-free number

How toll-free numbers appear on your account

Common toll-free rejections

Next steps

10DLC campaigns

Toll-free endpoint

Build it with the Messaging API

Toll-free endpoint

WebSocket events

Sending SMS

Messaging webhooks

​Verification fields

​Registry values

​Verify a toll-free number

​How toll-free numbers appear on your account

​Common toll-free rejections

​Next steps

10DLC campaigns

Toll-free endpoint

​Build it with the Messaging API

Toll-free endpoint

WebSocket events

Sending SMS

Messaging webhooks

Verification fields

Registry values

Verify a toll-free number

How toll-free numbers appear on your account

Common toll-free rejections

Next steps

Build it with the Messaging API