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

# Vobiz Messaging API - 10DLC registration

> Register US brands, 10DLC campaigns and toll-free verifications with the Vobiz Messaging API, upload supporting documents and track registry review.

The 10DLC endpoints register your business and your messaging programs with the US 10DLC registry, so US carriers deliver your application-to-person traffic. A **brand** describes the business that sends messages. A **campaign** describes one messaging program that runs under a brand and lists the numbers that send it. Toll-free verification uses the same campaign resource, with the business details inside the request instead of a brand.

All paths are relative to `https://api.vobiz.ai/api/v1/sms` and take the `X-Auth-ID` and `X-Auth-Token` headers.

<Warning>
  Registering a brand or campaign, vetting a brand, appealing and deregistering all submit your business to the US 10DLC registry for review. Run them only with your own credentials, with accurate business details, and when you intend to submit.
</Warning>

## The brand object

| Field | Type | Meaning |
| - | - | - |
| `id` | string (UUID) | Brand ID. Use it in `/10dlc/brands/{id}` paths and as `brandId` on campaigns. |
| `accountId` | string | Your Vobiz account ID. |
| `name` | string | Display name you gave the brand. |
| `legalName` | string | Registered legal name of the business. |
| `brandType` | string | `TENDLC_PRIVATE_COMPANY`, `TENDLC_PUBLIC_COMPANY`, `TENDLC_NON_PROFIT`, `TENDLC_GOVERNMENT` or `TOLL_FREE_NUMBER`. |
| `stage` | string | `DRAFT` until you register the brand, then `SUBMITTED`. |
| `registrationStatus` | string | Registrar decision after submission: `PENDING`, `PENDING_2FA`, `PENDING_APPEAL`, `ACTIVE` or `REJECTED`. |
| `brandIdentityStatus` | string | Identity result from the registry, for example `VERIFIED`. |
| `rejectionReasons` | array | One entry per registrar rejection: `registrar`, `state`, `rejectionReason`. |
| `website`, `supportEmail`, `supportPhone` | string | Public contact details of the business. `supportPhone` is E.164. |
| `vertical` | string | Industry code, for example `TECHNOLOGY`. |
| `taxId`, `taxIdIssuingCountry`, `countryCode` | string | Tax identifier and ISO 3166-1 alpha-2 countries. |
| `address` | object | `street`, `city`, `state`, `zipCode`. |
| `businessContactFirstName`, `businessContactLastName`, `businessContactEmail` | string | The person the registry contacts. 2FA requests go to the email. |
| `businessDba`, `legalEntityType`, `businessRegistrationType`, `stockExchange`, `stockSymbol`, `taxExemptStatus`, `alternateBusinessId` | string / object | Further registry details, sent when they apply to your business. |
| `lastSyncedAt`, `createdAt`, `updatedAt` | string (ISO 8601) | Last registry refresh, creation and last change. |

Optional fields are omitted from the response when they are empty.

## The campaign object

| Field | Type | Meaning |
| - | - | - |
| `id` | string (UUID) | Campaign ID. Use it in `/10dlc/campaigns/{id}` paths. |
| `accountId` | string | Your Vobiz account ID. |
| `brandId` | string (UUID) | Brand the campaign runs under. Omitted for toll-free campaigns. |
| `name` | string | Name you gave the campaign. |
| `campaignType` | string | `TEN_DIGIT_LONG_CODE` for standard 10DLC, `TOLL_FREE_UNIFIED_NUMBER` for toll-free verification, or another registry campaign type. |
| `stage` | string | Registry lifecycle stage, for example `DRAFT`, `IN_REVIEW`, `REGISTERED` or `REJECTED`. Treat it as an open string. |
| `programSummary`, `confirmationMessage`, `helpMessage`, `stopMessage` | string | How the program works and the replies it sends. |
| `customerCarePhone`, `customerCareEmail` | string | Customer care contact for the program. |
| `exampleMessages` | array of strings | Sample messages as the campaign sends them. |
| `termsAndConditionsUrl`, `privacyPolicyUrl` | string | Public policy URLs. |
| `useCases`, `messageTypes` | array of strings | Registry use-case codes and message types, for example `ALERTS` and `SMS`. |
| `optIns` | object | How recipients consent, keyed by channel such as `web`. |
| `lowVolume`, `ageGated`, `directLending`, `embeddedLink`, `embeddedPhone` | boolean | Content declarations. Always present; `false` unless you set them. |
| `numbers` | array of strings | Numbers recorded on the campaign on your account. |
| `rejectionReasons` | object | Registry review feedback after a rejection: `rejectionDate`, `rejectionReasons`, `rejectionDetails`. |
| `lastSyncedAt`, `createdAt`, `updatedAt` | string (ISO 8601) | Last registry refresh, creation and last change. |

## Endpoints

### Brands

| Method | Endpoint | What it does |
| - | - | - |
| `POST` | [`/10dlc/brands`](/docs/sms/api/10dlc/create-brand) | Create a brand in `DRAFT` stage. |
| `GET` | [`/10dlc/brands`](/docs/sms/api/10dlc/list-brands) | List every brand on your account. |
| `GET` | [`/10dlc/brands/{id}`](/docs/sms/api/10dlc/get-brand) | Retrieve a brand, refreshed from the registry. |
| `PUT` | [`/10dlc/brands/{id}`](/docs/sms/api/10dlc/update-brand) | Replace a brand's details. |
| `DELETE` | [`/10dlc/brands/{id}`](/docs/sms/api/10dlc/delete-brand) | Delete a brand that has no campaigns. |
| `POST` | [`/10dlc/brands/{id}/register`](/docs/sms/api/10dlc/register-brand) | Submit the brand for identity verification. |
| `GET` | [`/10dlc/brands/{id}/registrar-statuses`](/docs/sms/api/10dlc/brand-registrar-statuses) | See the brand's state at each registrar. |
| `POST` | [`/10dlc/brands/{id}/brand-auth-verification`](/docs/sms/api/10dlc/brand-auth-verification) | Start brand authentication for a public company. |
| `POST` | [`/10dlc/brands/{id}/resend-2fa`](/docs/sms/api/10dlc/resend-2fa) | Resend the brand-authentication request. |
| `POST` | [`/10dlc/brands/{id}/vet`](/docs/sms/api/10dlc/vet-brand) | Request an external vet of the brand. |
| `GET` | [`/10dlc/brands/{id}/vets`](/docs/sms/api/10dlc/list-brand-vets) | List the brand's vetting records. |

### Campaigns

| Method | Endpoint | What it does |
| - | - | - |
| `POST` | [`/10dlc/campaigns`](/docs/sms/api/10dlc/create-campaign) | Create a 10DLC campaign under a brand. |
| `POST` | [`/10dlc/campaigns/toll-free`](/docs/sms/api/10dlc/create-toll-free-campaign) | Create a toll-free verification campaign. |
| `GET` | [`/10dlc/campaigns`](/docs/sms/api/10dlc/list-campaigns) | List every campaign on your account. |
| `GET` | [`/10dlc/campaigns/priorities`](/docs/sms/api/10dlc/campaign-priorities) | List priority options for toll-free campaigns. |
| `GET` | [`/10dlc/campaigns/{id}`](/docs/sms/api/10dlc/get-campaign) | Retrieve a campaign, refreshed from the registry. |
| `PUT` | [`/10dlc/campaigns/{id}`](/docs/sms/api/10dlc/update-campaign) | Replace a 10DLC campaign's details. |
| `DELETE` | [`/10dlc/campaigns/{id}`](/docs/sms/api/10dlc/delete-campaign) | Delete a draft, rejected or deregistered campaign. |
| `POST` | [`/10dlc/campaigns/{id}/register`](/docs/sms/api/10dlc/register-campaign) | Submit the campaign for review. |
| `POST` | [`/10dlc/campaigns/{id}/deregister`](/docs/sms/api/10dlc/deregister-campaign) | Withdraw a registered campaign. |
| `POST` | [`/10dlc/campaigns/{id}/appeal`](/docs/sms/api/10dlc/appeal-campaign) | Appeal a rejection. |
| `POST` | [`/10dlc/campaigns/{id}/update-registration`](/docs/sms/api/10dlc/update-campaign-registration) | Update the numbers a registered campaign covers. |
| `GET` | [`/10dlc/campaigns/{id}/network-statuses`](/docs/sms/api/10dlc/campaign-network-statuses) | See the campaign's status on each carrier network. |
| `GET` | [`/10dlc/campaigns/{id}/numbers`](/docs/sms/api/10dlc/list-campaign-numbers) | List the numbers attached at the registry. |
| `POST` | [`/10dlc/campaigns/{id}/numbers`](/docs/sms/api/10dlc/add-campaign-numbers) | Attach numbers to a campaign. |
| `DELETE` | [`/10dlc/campaigns/{id}/numbers`](/docs/sms/api/10dlc/remove-campaign-numbers) | Detach numbers from a campaign. |

### Documents

| Method | Endpoint | What it does |
| - | - | - |
| `POST` | [`/10dlc/documents`](/docs/sms/api/10dlc/upload-document) | Upload a supporting document or MMS sample file, up to 10 MB. |
| `GET` | [`/10dlc/documents/{id}`](/docs/sms/api/10dlc/get-document) | Download an uploaded document by its `documentId`. |

## Registration lifecycle

<Steps>
  <Step title="Create the brand">
    `POST /10dlc/brands` with at least `name` and `brandType`. The brand starts in `DRAFT`.
  </Step>

  <Step title="Register the brand">
    `POST /10dlc/brands/{id}/register` moves it to `SUBMITTED`. `registrationStatus` starts at `PENDING` and settles at `ACTIVE` or `REJECTED`. A `TENDLC_PUBLIC_COMPANY` brand also completes brand authentication and shows `PENDING_2FA` until its business contact does.
  </Step>

  <Step title="Create and register a campaign">
    Upload any documents, then `POST /10dlc/campaigns` with `name` and `brandId`. The campaign starts in `DRAFT`. `POST /10dlc/campaigns/{id}/register` submits it, and `stage` moves through review until it reaches `REGISTERED` or `REJECTED`.
  </Step>

  <Step title="Attach numbers and check the networks">
    Attach sending numbers with `POST /10dlc/campaigns/{id}/numbers`, then use `GET /10dlc/campaigns/{id}/network-statuses` to see which carriers have provisioned the campaign.
  </Step>
</Steps>

If a campaign is rejected, read `rejectionReasons`, fix it with `PUT /10dlc/campaigns/{id}` and either register it again or file an appeal. To follow changes without polling, listen for the `10dlc.brand.updated` and `10dlc.campaign.updated` events on the [WebSocket](/docs/sms/websocket).

## Behaviour to know

* **Retrieves refresh from the registry.** `GET /10dlc/brands/{id}` and `GET /10dlc/campaigns/{id}` refresh the record from the registry before returning it. `lastSyncedAt` shows when that last succeeded. The list endpoints return the stored records without a refresh.
* **Lists are bare arrays.** `GET /10dlc/brands` and `GET /10dlc/campaigns` return every record, newest first, with no pagination. `GET /10dlc/brands/{id}/vets` is the one paged list: `page` from 0 and `size` from 0 to 100 (default 20).
* **Idempotent creates.** Pass a `referenceId` on brand and campaign creates. A retry with the same value, for example after a `502`, reconciles to the same record.
* **Updates replace.** `PUT` on a brand or campaign replaces the whole object, so send every field you want to keep. `name` (and `brandType` for brands) is required on every update. `PUT` applies to 10DLC campaigns; a toll-free campaign returns `400`.
* **Delete order.** A brand with campaigns returns `409`. Deregister registered campaigns, delete the campaigns, then delete the brand.
* **Registry pass-through.** Vetting records, priority options, network statuses and campaign numbers come straight from the registry, so read the fields you need and ignore the rest.

## Errors

Every error is a JSON object with an `error` message. When the registry is involved, the body also carries `providerError`, an opaque diagnostic string you can quote to support.

| Status | When |
| - | - |
| `400` | A required field is missing or a value is invalid, for example `invalid request: name is required`. |
| `404` | The brand, campaign or document is not on your account, or the ID is not a UUID. |
| `409` | A conflict, for example deleting a brand that still has campaigns. |
| `413` | A document upload is larger than 10 MB. |
| `422` | The registry rejected the request; `error` carries its description. |
| `429` | The registry rate-limited the request. Retry later. |
| `502` | The registry did not answer. Retry, with the same `referenceId` on creates. |
| `503` | The registry did not accept Vobiz's service credentials. Retry later or contact support. |

## Example: create a brand

```bash cURL theme={null}
curl -X POST "https://api.vobiz.ai/api/v1/sms/10dlc/brands" \
  -H "X-Auth-ID: MA_XXXXXXXX" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "brand-example-corp-01",
    "name": "Example Corp",
    "legalName": "Example Corporation Inc.",
    "brandType": "TENDLC_PRIVATE_COMPANY",
    "legalEntityType": "PRIVATE_COMPANY",
    "vertical": "TECHNOLOGY",
    "website": "https://example.com",
    "supportEmail": "support@example.com",
    "supportPhone": "+14155550100",
    "taxId": "12-3456789",
    "taxIdIssuingCountry": "US",
    "countryCode": "US",
    "address": {"street": "100 Example Street", "city": "San Francisco", "state": "CA", "zipCode": "94105"},
    "businessContactFirstName": "Alex",
    "businessContactLastName": "Doe",
    "businessContactEmail": "alex.doe@example.com"
  }'
```

```json 201 Created theme={null}
{
  "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
  "accountId": "MA_XXXXXXXX",
  "name": "Example Corp",
  "legalName": "Example Corporation Inc.",
  "brandType": "TENDLC_PRIVATE_COMPANY",
  "stage": "DRAFT",
  "website": "https://example.com",
  "supportEmail": "support@example.com",
  "supportPhone": "+14155550100",
  "vertical": "TECHNOLOGY",
  "taxId": "12-3456789",
  "taxIdIssuingCountry": "US",
  "countryCode": "US",
  "address": {"street": "100 Example Street", "city": "San Francisco", "state": "CA", "zipCode": "94105"},
  "businessContactFirstName": "Alex",
  "businessContactLastName": "Doe",
  "businessContactEmail": "alex.doe@example.com",
  "legalEntityType": "PRIVATE_COMPANY",
  "createdAt": "2026-10-12T10:30:00Z",
  "updatedAt": "2026-10-12T10:30:00Z"
}
```

## Related

<CardGroup cols={2}>
  <Card title="Compliance overview" icon="shield-check" href="/docs/sms/compliance/overview">
    Which registration your traffic needs.
  </Card>

  <Card title="Register a 10DLC brand" icon="building" href="/docs/sms/compliance/us-10dlc-brands">
    Step-by-step brand registration and vetting.
  </Card>

  <Card title="Register a 10DLC campaign" icon="bullhorn" href="/docs/sms/compliance/us-10dlc-campaigns">
    Campaign fields, review and attaching numbers.
  </Card>

  <Card title="Toll-free verification" icon="phone" href="/docs/sms/compliance/us-toll-free">
    Verify toll-free numbers for messaging.
  </Card>

  <Card title="WebSocket events" icon="bolt" href="/docs/sms/websocket">
    Get brand and campaign updates as they happen.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/docs/sms/errors">
    Error format and status codes across the API.
  </Card>
</CardGroup>


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