Create a campaign

POST

10dlc

campaigns

cURL

curl --request POST \
  --url https://api.vobiz.ai/api/v1/sms/10dlc/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "brandId": "5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60",
  "name": "Example Corp account alerts"
}
'

from vobiz import Vobiz

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

client.sms.campaigns.create_campaign(
    name="Example Corp account alerts",
    program_summary="Example Corp sends account and support alerts to customers who opted in on the sign-up form. Reply STOP to opt out, HELP for help.",
    confirmation_message="Example Corp: You are subscribed to account alerts. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to opt out.",
    help_message="Example Corp: For help email support@example.com. Reply STOP to opt out.",
    stop_message="Example Corp: You have been unsubscribed. Reply HELP for help.",
    customer_care_phone="+14155550100",
    customer_care_email="support@example.com",
    terms_and_conditions_url="https://example.com/terms",
    privacy_policy_url="https://example.com/privacy",
    example_messages=[
        "Example Corp: Your support ticket #48213 was updated. View it at https://example.com/support. Reply STOP to opt out.",
        "Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out."
    ],
    use_cases=[
        "ALERTS"
    ],
    message_types=[
        "SMS"
    ],
    opt_ins={
        "web": {"url": "https://example.com/signup", "callToAction": "By checking this box you agree to receive account alerts from Example Corp. Msg frequency varies. Msg & data rates may apply. Reply STOP to opt out, HELP for help."}
    },
    low_volume=True,
    embedded_link=True,
    numbers=[
        "14155550100"
    ],
    reference_id="campaign-account-alerts-01",
    brand_id="5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60",
    campaign_type="TEN_DIGIT_LONG_CODE",
)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    brandId: '5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60',
    name: 'Example Corp account alerts'
  })
};

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

{
  "id": "8a7d2f10-3c4b-4e9a-b1d2-6e5f4a3b2c11",
  "accountId": "MA_XXXXXXXX",
  "brandId": "5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60",
  "name": "Example Corp account alerts",
  "campaignType": "TEN_DIGIT_LONG_CODE",
  "stage": "DRAFT",
  "programSummary": "Example Corp sends account and support alerts to customers who opted in on the sign-up form. Reply STOP to opt out, HELP for help.",
  "confirmationMessage": "Example Corp: You are subscribed to account alerts. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to opt out.",
  "helpMessage": "Example Corp: For help email support@example.com. Reply STOP to opt out.",
  "stopMessage": "Example Corp: You have been unsubscribed. Reply HELP for help.",
  "customerCarePhone": "+14155550100",
  "customerCareEmail": "support@example.com",
  "exampleMessages": [
    "Example Corp: Your support ticket #48213 was updated. View it at https://example.com/support. Reply STOP to opt out.",
    "Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out."
  ],
  "termsAndConditionsUrl": "https://example.com/terms",
  "privacyPolicyUrl": "https://example.com/privacy",
  "useCases": [
    "ALERTS"
  ],
  "messageTypes": [
    "SMS"
  ],
  "optIns": {
    "web": {
      "url": "https://example.com/signup",
      "callToAction": "By checking this box you agree to receive account alerts from Example Corp. Msg frequency varies. Msg & data rates may apply. Reply STOP to opt out, HELP for help."
    }
  },
  "lowVolume": true,
  "ageGated": false,
  "directLending": false,
  "embeddedLink": true,
  "embeddedPhone": false,
  "numbers": [
    "14155550100"
  ],
  "createdAt": "2026-10-06T14:28:25Z",
  "updatedAt": "2026-10-06T14:28:25Z"
}

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

Body of a 10DLC campaign create: the shared campaign fields plus the brand, type and idempotency reference. name and brandId are required.

name

string

required

Name for the campaign, for your reference. Required on create and on update.

Example:

"Example Corp account alerts"

brandId

string<uuid>

required

Required. ID of the brand from POST /10dlc/brands that runs this campaign. A missing, unknown or non-UUID value returns 404 with {"error":"brand not found"}.

Example:

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

programSummary

string

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

Example:

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

confirmationMessage

string

Message you send when a recipient opts in. Include your brand name and how to get help or opt out.

Example:

"Example Corp: You are subscribed to account alerts. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to opt out."

helpMessage

string

Reply you send when a recipient texts HELP. Include your brand name and a way to reach support.

Example:

"Example Corp: For help email support@example.com. Reply STOP to opt out."

stopMessage

string

Reply you send when a recipient texts STOP, confirming they will receive no further messages.

Example:

"Example Corp: You have been unsubscribed. Reply HELP for help."

customerCarePhone

string

Customer care phone number for the program, in E.164 format.

Example:

"+14155550100"

customerCareEmail

string<email>

Customer care email address for the program.

Example:

"support@example.com"

termsAndConditionsUrl

string<uri>

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

Example:

"https://example.com/terms"

privacyPolicyUrl

string<uri>

Public URL of your privacy policy.

Example:

"https://example.com/privacy"

exampleMessages

string[]

Sample messages exactly as the campaign will send them, including your brand name and opt-out language. Cover each use case you list.

Example:

[
  "Example Corp: Your support ticket #48213 was updated. View it at https://example.com/support. Reply STOP to opt out."
]

useCases

string[]

Use-case codes the campaign covers. Values accepted by the US 10DLC registry: TWO_FACTOR_AUTH, ALERTS, FRAUD_ALERTS, CHAT, PROMOTIONAL_MARKETING, EDUCATION, DONATION, PUBLIC_SERVICE_ANNOUNCEMENT, VOTING_POLLING, POLITICAL, M2M, SWEEPSTAKE.

Example:

["ALERTS"]

messageTypes

string[]

Message types the campaign sends, for example SMS and MMS.

Example:

["SMS"]

optIns

object

How recipients give consent, as an object keyed by opt-in channel (for example web, keyword, paper). Each entry describes that flow, for example url and callToAction for web; the object is passed to the registry as given.

Example:

{
  "web": {
    "url": "https://example.com/signup",
    "callToAction": "By checking this box you agree to receive account alerts from Example Corp. Msg frequency varies. Msg & data rates may apply. Reply STOP to opt out, HELP for help."
  }
}

lowVolume

boolean

default:false

Declares the campaign as low volume to the registry. Defaults to false.

ageGated

boolean

default:false

Set true when the content is restricted to adults. Defaults to false.

directLending

boolean

default:false

Set true when the content relates to direct lending or loan arrangements. Defaults to false.

embeddedLink

boolean

default:false

Set true when messages contain URLs. Defaults to false.

embeddedPhone

boolean

default:false

Set true when messages contain phone numbers. Defaults to false.

numbers

string[]

Numbers on your account to attach to the campaign, as digits with country code and no + (for example 14155550100).

Example:

["14155550100"]

supportingDocuments

string<uuid>[]

documentId values of supporting documents uploaded with POST /10dlc/documents. Every ID must be on your account, otherwise the request returns 400.

mmsSampleFiles

string<uuid>[]

documentId values of MMS sample files uploaded with POST /10dlc/documents. Every ID must be on your account, otherwise the request returns 400.

referenceId

string

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

Example:

"campaign-account-alerts-01"

campaignType

enum<string>

default:TEN_DIGIT_LONG_CODE

Kind of campaign. Defaults to TEN_DIGIT_LONG_CODE, the standard 10DLC campaign. Toll-free types return 400; use POST /10dlc/campaigns/toll-free for those.

Available options:

TEN_DIGIT_LONG_CODE,

EXTERNAL_TEN_DIGIT_LONG_CODE,

DCA2_TEN_DIGIT_LONG_CODE,

SHORT_CODE,

RCS_SENDER_LAUNCH

Response

The campaign was created in DRAFT stage.

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 \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "brandId": "5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60",
  "name": "Example Corp account alerts"
}
'

from vobiz import Vobiz

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

client.sms.campaigns.create_campaign(
    name="Example Corp account alerts",
    program_summary="Example Corp sends account and support alerts to customers who opted in on the sign-up form. Reply STOP to opt out, HELP for help.",
    confirmation_message="Example Corp: You are subscribed to account alerts. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to opt out.",
    help_message="Example Corp: For help email support@example.com. Reply STOP to opt out.",
    stop_message="Example Corp: You have been unsubscribed. Reply HELP for help.",
    customer_care_phone="+14155550100",
    customer_care_email="support@example.com",
    terms_and_conditions_url="https://example.com/terms",
    privacy_policy_url="https://example.com/privacy",
    example_messages=[
        "Example Corp: Your support ticket #48213 was updated. View it at https://example.com/support. Reply STOP to opt out.",
        "Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out."
    ],
    use_cases=[
        "ALERTS"
    ],
    message_types=[
        "SMS"
    ],
    opt_ins={
        "web": {"url": "https://example.com/signup", "callToAction": "By checking this box you agree to receive account alerts from Example Corp. Msg frequency varies. Msg & data rates may apply. Reply STOP to opt out, HELP for help."}
    },
    low_volume=True,
    embedded_link=True,
    numbers=[
        "14155550100"
    ],
    reference_id="campaign-account-alerts-01",
    brand_id="5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60",
    campaign_type="TEN_DIGIT_LONG_CODE",
)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    brandId: '5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60',
    name: 'Example Corp account alerts'
  })
};

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

{
  "id": "8a7d2f10-3c4b-4e9a-b1d2-6e5f4a3b2c11",
  "accountId": "MA_XXXXXXXX",
  "brandId": "5f1c3a2e-7b4d-4e8f-9a0b-1c2d3e4f5a60",
  "name": "Example Corp account alerts",
  "campaignType": "TEN_DIGIT_LONG_CODE",
  "stage": "DRAFT",
  "programSummary": "Example Corp sends account and support alerts to customers who opted in on the sign-up form. Reply STOP to opt out, HELP for help.",
  "confirmationMessage": "Example Corp: You are subscribed to account alerts. Msg frequency varies. Msg & data rates may apply. Reply HELP for help, STOP to opt out.",
  "helpMessage": "Example Corp: For help email support@example.com. Reply STOP to opt out.",
  "stopMessage": "Example Corp: You have been unsubscribed. Reply HELP for help.",
  "customerCarePhone": "+14155550100",
  "customerCareEmail": "support@example.com",
  "exampleMessages": [
    "Example Corp: Your support ticket #48213 was updated. View it at https://example.com/support. Reply STOP to opt out.",
    "Example Corp: Your account balance is low. Add funds at https://example.com/wallet. Reply STOP to opt out."
  ],
  "termsAndConditionsUrl": "https://example.com/terms",
  "privacyPolicyUrl": "https://example.com/privacy",
  "useCases": [
    "ALERTS"
  ],
  "messageTypes": [
    "SMS"
  ],
  "optIns": {
    "web": {
      "url": "https://example.com/signup",
      "callToAction": "By checking this box you agree to receive account alerts from Example Corp. Msg frequency varies. Msg & data rates may apply. Reply STOP to opt out, HELP for help."
    }
  },
  "lowVolume": true,
  "ageGated": false,
  "directLending": false,
  "embeddedLink": true,
  "embeddedPhone": false,
  "numbers": [
    "14155550100"
  ],
  "createdAt": "2026-10-06T14:28:25Z",
  "updatedAt": "2026-10-06T14:28:25Z"
}

Getting Started

API Reference

Guides

Create a campaign

Authorizations

Body

Response