Create a toll-free campaign

POST

10dlc

campaigns

toll-free

cURL

curl --request POST \
  --url https://api.vobiz.ai/api/v1/sms/10dlc/campaigns/toll-free \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "name": "Example Corp toll-free notifications"
}
'

from vobiz import Vobiz

client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")

from vobiz.sms import BrandAddress

client.sms.campaigns.create_toll_free_campaign(
    reference_id="tollfree-notifications-01",
    name="Example Corp toll-free notifications",
    privacy_policy_url="https://example.com/privacy",
    terms_and_conditions_url="https://example.com/terms",
    message_volume="TEN_THOUSAND",
    numbers=[
        "+18335550100"
    ],
    use_case="NOTIFICATIONS",
    program_summary="Example Corp sends account and support notifications to customers who opted in on the contact form. Reply STOP to opt out, HELP for help.",
    example_message="Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out, HELP for help.",
    opt_ins={
        "web": {"url": "https://example.com/contact", "callToAction": "By checking this box you agree to receive account notifications from Example Corp. Reply STOP to opt out, HELP for help."}
    },
    opt_in_image_ur_ls=[
        "https://example.com/opt-in-screenshot.png"
    ],
    country_code="US",
    address=BrandAddress(
        street="100 Example Street",
        city="San Francisco",
        state="CA",
        zip_code="94105",
    ),
    support_phone="+14155550100",
    support_email="support@example.com",
    business_contact_first_name="Alex",
    business_contact_last_name="Doe",
    legal_name="Example Corporation Inc.",
    business_name="Example Corp",
    business_website="https://example.com",
    customer_care_email="support@example.com",
    tax_id="12-3456789",
    tax_id_issuing_country="US",
    legal_entity_type="PRIVATE_COMPANY",
)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: 'Example Corp toll-free notifications'})
};

fetch('https://api.vobiz.ai/api/v1/sms/10dlc/campaigns/toll-free', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "9c1b3e5f-7a2d-4b8c-a0e1-2f3d4c5b6a72",
  "accountId": "MA_XXXXXXXX",
  "name": "Example Corp toll-free notifications",
  "campaignType": "TOLL_FREE_UNIFIED_NUMBER",
  "stage": "DRAFT",
  "programSummary": "Example Corp sends account and support notifications to customers who opted in on the contact form. Reply STOP to opt out, HELP for help.",
  "customerCarePhone": "+14155550100",
  "customerCareEmail": "support@example.com",
  "exampleMessages": [
    "Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out, HELP for help."
  ],
  "termsAndConditionsUrl": "https://example.com/terms",
  "privacyPolicyUrl": "https://example.com/privacy",
  "useCases": [
    "NOTIFICATIONS"
  ],
  "optIns": {
    "web": {
      "url": "https://example.com/contact",
      "callToAction": "By checking this box you agree to receive account notifications from Example Corp. Reply STOP to opt out, HELP for help."
    }
  },
  "lowVolume": false,
  "ageGated": false,
  "directLending": false,
  "embeddedLink": false,
  "embeddedPhone": false,
  "numbers": [
    "+18335550100"
  ],
  "createdAt": "2026-10-08T04:36:40Z",
  "updatedAt": "2026-10-08T04:36:40Z"
}

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token

string

header

required

Your Vobiz account Auth Token.

Body

application/json

Toll-free verification request. The business details travel inside the request, so no brandId is needed; only name is required, but the reviewer checks every field you send.

name

string

required

Name for the toll-free campaign, for your reference. Required (400 with invalid request: name is required otherwise).

Example:

"Example Corp toll-free notifications"

referenceId

string

Your own idempotency reference. Repeating a create with the same value reconciles to the same campaign instead of creating a second one.

Example:

"tollfree-notifications-01"

privacyPolicyUrl

string<uri>

Public URL of your privacy policy.

Example:

"https://example.com/privacy"

termsAndConditionsUrl

string<uri>

Public URL of the terms and conditions that cover the program.

Example:

"https://example.com/terms"

messageVolume

string

Expected monthly message volume. Values accepted by the US 10DLC registry: HUNDRED, TEN_THOUSAND, TWO_HUNDRED_FIFTY_THOUSAND, SEVEN_HUNDRED_FIFTY_THOUSAND, FIVE_MILLION.

Example:

"TEN_THOUSAND"

numbers

string[]

Toll-free numbers on your account to verify, in E.164 format (for example +18885550100).

Example:

["+18335550100"]

numberKeys

string[]

Registry number keys of the numbers to verify, as an alternative to numbers.

useCase

string

Main use case of the program. Values accepted by the US 10DLC registry: 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.

Example:

"NOTIFICATIONS"

programSummary

string

Plain-language description of the program: what you send, to whom, how often and how recipients opt in.

Example:

"Example Corp sends account and support notifications to customers who opted in on the contact form. Reply STOP to opt out, HELP for help."

exampleMessage

string

A sample message exactly as you will send it, including your brand name and opt-out language.

Example:

"Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out, HELP for help."

optIns

object

How recipients give consent, as an object keyed by opt-in channel (for example web with url and callToAction). Passed to the registry as given.

Example:

{
  "web": {
    "url": "https://example.com/contact",
    "callToAction": "By checking this box you agree to receive account notifications from Example Corp. Reply STOP to opt out, HELP for help."
  }
}

optInImageURLs

string<uri>[]

Public URLs of screenshots or images that show the opt-in flow to the reviewer.

Example:

["https://example.com/opt-in-screenshot.png"]

additionalInformation

string

Anything else the reviewer should know about the program, in plain text.

countryCode

string

ISO 3166-1 alpha-2 code of the country where the business is registered.

Example:

"US"

address

object

Postal address of the business as it appears on its registration records.

Show child attributes

supportPhone

string

Support phone number for the business, in E.164 format.

Example:

"+14155550100"

supportEmail

string<email>

Support email address for the business.

Example:

"support@example.com"

businessContactFirstName

string

First name of the person the reviewer can contact about the business.

Example:

"Alex"

businessContactLastName

string

Last name of the person the reviewer can contact about the business.

Example:

"Doe"

legalName

string

Registered legal name of the business, exactly as it appears on tax records.

Example:

"Example Corporation Inc."

businessDBA

string

Trading name ("doing business as") when it differs from legalName. Note the casing businessDBA on this endpoint, unlike businessDba on brands.

businessName

string

Business name customers know you by.

Example:

"Example Corp"

businessWebsite

string<uri>

Business website. It must be live and match the business.

Example:

"https://example.com"

customerCareEmail

string<email>

Customer care email address for the program.

Example:

"support@example.com"

taxId

string

Tax identifier of the business, for example the US EIN.

Example:

"12-3456789"

taxIdIssuingCountry

string

ISO 3166-1 alpha-2 code of the country that issued taxId.

Example:

"US"

legalEntityType

string

Legal form of the business. Values accepted by the US 10DLC registry: PRIVATE_COMPANY, PUBLIC_COMPANY, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR.

Example:

"PRIVATE_COMPANY"

businessRegistrationType

string

Type of registration number for a business outside the US. Values accepted by the US 10DLC registry: VAT, CBN, PROVINCIAL_NUMBER, ABN, SIREN, NZBN, CIF, CNPJ, OTHER.

campaignVerifyToken

string

Campaign Verify token for a US political program. Omit it for every other program.

priorityId

string<uuid>

ID (UUID) of a priority option from GET /10dlc/campaigns/priorities. A value that is not a UUID returns 400; omit it when the list is empty.

Response

The toll-free campaign was created.

A 10DLC or toll-free campaign on your account and its state at the US 10DLC registry. Optional fields are omitted when empty, and registry state is refreshed when you retrieve the campaign.

string<uuid>

Campaign ID (UUID) on your account. Use it in every /10dlc/campaigns/{id} path.

Example:

"8a7d2f10-3c4b-4e9a-b1d2-6e5f4a3b2c11"

accountId

string

Your Vobiz account ID (MA_...). Always the account whose credentials made the request.

Example:

"MA_XXXXXXXX"

brandId

string<uuid>

ID of the brand the campaign runs under. Omitted for toll-free campaigns, which carry their business details themselves.

Example:

"5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60"

name

string

Name you gave the campaign, for your reference.

Example:

"Example Corp account alerts"

campaignType

enum<string>

Kind of campaign. TEN_DIGIT_LONG_CODE is a standard 10DLC campaign (the default on create) and TOLL_FREE_UNIFIED_NUMBER is a toll-free verification created with POST /10dlc/campaigns/toll-free. The other values are registry campaign types you can request on create.

Available options:

TEN_DIGIT_LONG_CODE,

TOLL_FREE_UNIFIED_NUMBER,

TOLL_FREE_NUMBER,

SHORT_CODE,

EXTERNAL_TEN_DIGIT_LONG_CODE,

DCA2_TEN_DIGIT_LONG_CODE,

TOLL_FREE_EXTERNALLY_VERIFIED,

RCS_SENDER_LAUNCH

stage

string

Registry lifecycle stage. A new campaign is DRAFT; after you register it, it moves through review stages such as SUBMITTED, IN_REVIEW or APPEALED and settles at REGISTERED or REJECTED. Other values include REGISTERED_PENDING_UPDATE, REGISTERED_PENDING_DEREGISTRATION, REJECTED_EXTERNALLY, DEREGISTERED, ARCHIVED, BLOCKED, SUSPENDED and DELETED; treat it as an open string.

Example:

"REGISTERED"

programSummary

string

Description of the program as submitted to the registry. Omitted when not set.

confirmationMessage

string

Opt-in confirmation message as submitted. Omitted when not set.

helpMessage

string

HELP reply as submitted. Omitted when not set.

stopMessage

string

STOP reply as submitted. Omitted when not set.

customerCarePhone

string

Customer care phone number, in E.164 format. Omitted when not set.

Example:

"+14155550100"

customerCareEmail

string

Customer care email address. Omitted when not set.

Example:

"support@example.com"

exampleMessages

string[]

Sample messages as submitted. Omitted when not set.

termsAndConditionsUrl

string<uri>

Public URL of your terms and conditions. Omitted when not set.

privacyPolicyUrl

string<uri>

Public URL of your privacy policy. Omitted when not set.

useCases

string[]

Use-case codes as submitted, for example ALERTS or, on a toll-free campaign, NOTIFICATIONS. Omitted when not set.

Example:

["ALERTS"]

messageTypes

string[]

Message types as submitted, for example SMS. Omitted when not set.

Example:

["SMS"]

optIns

object

Opt-in details as submitted, keyed by channel (for example web). Omitted when not set.

lowVolume

boolean

Whether the campaign is declared low volume. Always present; false unless you set it.

ageGated

boolean

Whether the content is restricted to adults. Always present; false unless you set it.

directLending

boolean

Whether the content relates to direct lending. Always present; false unless you set it.

embeddedLink

boolean

Whether messages contain URLs. Always present; false unless you set it.

embeddedPhone

boolean

Whether messages contain phone numbers. Always present; false unless you set it.

numbers

string[]

Numbers recorded on the campaign on your account. 10DLC campaigns store digits with country code (for example 14155550100); toll-free campaigns store E.164 with a leading +. For the registry's own list use GET /10dlc/campaigns/{id}/numbers.

Example:

["14155550100"]

rejectionReasons

object

The registry's review feedback after a rejection, with keys such as rejectionDate, rejectionReasons and rejectionDetails (each detail has errorCode, description, recommendedAction and rejectionCategory). Omitted when the campaign has no feedback; address every point before you appeal.

lastSyncedAt

string<date-time>

When Vobiz last refreshed this record from the US 10DLC registry, in ISO 8601 (RFC 3339) UTC. Omitted until the first refresh.

Example:

"2026-10-14T17:19:03Z"

createdAt

string<date-time>

When the record was created on your account, in ISO 8601 (RFC 3339) UTC.

Example:

"2026-10-06T14:28:25Z"

updatedAt

string<date-time>

When the record last changed on your account, in ISO 8601 (RFC 3339) UTC.

Example:

"2026-10-14T17:19:03Z"

⌘I

cURL

curl --request POST \
  --url https://api.vobiz.ai/api/v1/sms/10dlc/campaigns/toll-free \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "name": "Example Corp toll-free notifications"
}
'

from vobiz import Vobiz

client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")

from vobiz.sms import BrandAddress

client.sms.campaigns.create_toll_free_campaign(
    reference_id="tollfree-notifications-01",
    name="Example Corp toll-free notifications",
    privacy_policy_url="https://example.com/privacy",
    terms_and_conditions_url="https://example.com/terms",
    message_volume="TEN_THOUSAND",
    numbers=[
        "+18335550100"
    ],
    use_case="NOTIFICATIONS",
    program_summary="Example Corp sends account and support notifications to customers who opted in on the contact form. Reply STOP to opt out, HELP for help.",
    example_message="Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out, HELP for help.",
    opt_ins={
        "web": {"url": "https://example.com/contact", "callToAction": "By checking this box you agree to receive account notifications from Example Corp. Reply STOP to opt out, HELP for help."}
    },
    opt_in_image_ur_ls=[
        "https://example.com/opt-in-screenshot.png"
    ],
    country_code="US",
    address=BrandAddress(
        street="100 Example Street",
        city="San Francisco",
        state="CA",
        zip_code="94105",
    ),
    support_phone="+14155550100",
    support_email="support@example.com",
    business_contact_first_name="Alex",
    business_contact_last_name="Doe",
    legal_name="Example Corporation Inc.",
    business_name="Example Corp",
    business_website="https://example.com",
    customer_care_email="support@example.com",
    tax_id="12-3456789",
    tax_id_issuing_country="US",
    legal_entity_type="PRIVATE_COMPANY",
)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: 'Example Corp toll-free notifications'})
};

fetch('https://api.vobiz.ai/api/v1/sms/10dlc/campaigns/toll-free', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "9c1b3e5f-7a2d-4b8c-a0e1-2f3d4c5b6a72",
  "accountId": "MA_XXXXXXXX",
  "name": "Example Corp toll-free notifications",
  "campaignType": "TOLL_FREE_UNIFIED_NUMBER",
  "stage": "DRAFT",
  "programSummary": "Example Corp sends account and support notifications to customers who opted in on the contact form. Reply STOP to opt out, HELP for help.",
  "customerCarePhone": "+14155550100",
  "customerCareEmail": "support@example.com",
  "exampleMessages": [
    "Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out, HELP for help."
  ],
  "termsAndConditionsUrl": "https://example.com/terms",
  "privacyPolicyUrl": "https://example.com/privacy",
  "useCases": [
    "NOTIFICATIONS"
  ],
  "optIns": {
    "web": {
      "url": "https://example.com/contact",
      "callToAction": "By checking this box you agree to receive account notifications from Example Corp. Reply STOP to opt out, HELP for help."
    }
  },
  "lowVolume": false,
  "ageGated": false,
  "directLending": false,
  "embeddedLink": false,
  "embeddedPhone": false,
  "numbers": [
    "+18335550100"
  ],
  "createdAt": "2026-10-08T04:36:40Z",
  "updatedAt": "2026-10-08T04:36:40Z"
}

Getting Started

API Reference

Guides

Create a toll-free campaign

Authorizations

Body

Response