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

# SMS Registration

> Register your business and texting campaign for US numbers (10DLC) entirely through the API.

## Overview

US carriers require a business and a texting campaign to be registered before a workspace can text from US numbers. In the Sendora app that is two screens. In the API it is one resource, **SMS registrations**, with a `type` of `brand` (your business) or `campaign` (what you text and how people opt in).

The order is always the same:

1. Check **readiness** and, if you want, ask for a **quote**.
2. Create a **brand** draft, then **submit** it.
3. Create a **campaign** draft for that brand, then **submit** it.
4. **Attach** your numbers to the campaign.

Drafts are free and can be edited as often as you like. Submitting, the paid trust check and attaching numbers charge your wallet, and each one is quoted first.

All of these calls need an API key with write access, except the reads.

## 1. Check readiness and a quote

```bash theme={"dark"}
curl "https://api.sendora.ai/api/v1/public/sms-registrations?view=readiness&quote=brand&entity_type=company" \
  -H "X-API-Key: sk_live_..."
```

The response has `readiness` (can you text yet, and `next_step`), `options` (the exact values the forms accept: `entity_type` such as `company`, `sole_proprietor`, `nonprofit`, `government` or `public_company`, `vertical`, `use_case`, `opt_in_method` and more) and, when you ask for one, a `quote` with `total_due_now_cents`. Use `quote=campaign` with `use_case`, or `quote=vetting`, for the other fees.

## 2. Create a brand draft

Send an `Idempotency-Key` of 8 to 255 characters, so a retry returns the same draft instead of making a second one.

```bash theme={"dark"}
curl -X POST "https://api.sendora.ai/api/v1/public/sms-registrations" \
  -H "X-API-Key: sk_live_..." \
  -H "Idempotency-Key: create-brand-acme-1" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "brand",
    "entity_type": "company",
    "company_name": "Acme Plumbing",
    "ein": "12-3456789",
    "vertical": "PROFESSIONAL",
    "website": "https://acme.example",
    "email": "owner@acme.example",
    "phone": "+15551230000",
    "street": "1 Main St",
    "city": "Austin",
    "state_code": "TX",
    "postal_code": "78701",
    "country": "US"
  }'
```

A draft only needs `type` and `entity_type`. Use the values from `options`; a value that is not on the list answers `422`. Fill the rest in with `PATCH /sms-registrations/{id}`, sending only the fields to change and `type` again. The response lists `issues`, the fields still missing or wrong, so you know what to fix before you submit.

## 3. Submit the brand

```bash theme={"dark"}
curl -X POST "https://api.sendora.ai/api/v1/public/sms-registrations/BRAND_ID/actions" \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "brand", "action": "submit" }'
```

This charges the wallet for the registration fee. If the wallet is short, the call answers `402` and nothing is submitted. Read `state` and `status_text` on the brand to follow its review. A sole proprietor brand also needs its phone code: `action: "send_code"`, then `action: "verify_code"` with `pin`.

Other brand actions: `vetting` runs the optional paid trust check, and `revet` re-checks after you fix a problem.

## 4. Create and submit the campaign

```bash theme={"dark"}
curl -X POST "https://api.sendora.ai/api/v1/public/sms-registrations" \
  -H "X-API-Key: sk_live_..." \
  -H "Idempotency-Key: create-campaign-acme-1" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "campaign",
    "brand_public_id": "BRAND_ID",
    "use_case": "MARKETING",
    "description": "Appointment reminders and offers for Acme customers who opted in.",
    "message_flow": "Customers tick the text box on our booking form.",
    "opt_in_method": "web_form",
    "samples": ["Acme: your visit is tomorrow at 9am. Reply STOP to opt out."]
  }'
```

Then submit it with `{ "type": "campaign", "action": "submit" }`. Other campaign actions: `appeal` (with `reason`) after a rejection, `clone` to copy a finished campaign into a new draft, `attach_numbers` (with `phone_number_public_ids`) and `detach_number` (with `phone_number_public_id`). Attaching numbers charges the wallet.

## 5. Read, follow and clean up

```bash theme={"dark"}
# everything, or one type
curl "https://api.sendora.ai/api/v1/public/sms-registrations?type=campaign" -H "X-API-Key: sk_live_..."

# one registration with its timeline and attached numbers
curl "https://api.sendora.ai/api/v1/public/sms-registrations?type=campaign&id=CAMPAIGN_ID&include=events,numbers" \
  -H "X-API-Key: sk_live_..."

# delete a draft
curl -X DELETE "https://api.sendora.ai/api/v1/public/sms-registrations/CAMPAIGN_ID?type=campaign" \
  -H "X-API-Key: sk_live_..."
```

A registration with attached numbers or an active campaign cannot be deleted. The error says why.

## Assistants and the MCP

The Sendora MCP exposes the same steps. Reading and drafting are `read_channels` and `edit_channels`. The steps that charge the wallet (`submit_sms_registration`, `request_sms_vetting`, `attach_sms_numbers`) are in their own tool, `run_channels`, so an assistant has to ask for them on purpose. Read the quote and confirm with the person before it submits.

## Errors

| Status | Meaning |
| - | - |
| `402` | The wallet does not have enough credit for this step. Add funds and call it again. |
| `404` | No registration with that `type` and `id` in this workspace. |
| `409` | The step is not allowed in the registration's current state, for example submitting twice. |
| `422` | A field is missing or invalid, or `Idempotency-Key` is missing on a create. The body names the field. |


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