10DLC Registration Wizard

The wizard is the recommended way to complete TCR brand and campaign registration. It turns the linear single-shot flow into a guided, resumable process:

Save and resume — your draft persists across sessions, tabs, and weeks. Close the tab or come back tomorrow; you pick up where you left off.
Move between steps non-linearly — the wizard tracks brand, campaign, and review as independent steps. Fill the campaign samples while the brand section is still incomplete, and the progress payload keeps both counts.
Validate before you pay — per-field validation fires on every save, and a pre-submission lint pass scores the saved draft against known TCR rejection patterns before the upstream registration fee is charged.

The wizard writes to your organization’s own draft storage only. It does not hold, gate, or route any message traffic.

Why the wizard exists

The registry’s own brand and campaign flow asks for roughly 25 fields across two dense forms, validates them only after you submit, and saves nothing along the way. The wizard exists to remove the four failure modes operators hit most often in that flow:

Lost work — the linear flow has no save-as-you-go; closing a tab discards every keystroke. Here, each PUT /wizard/draft persists the draft, so a closed tab or a week away costs nothing.
Re-entered work after a rejection — brand vetting takes 1–3 business days, and in the linear flow a brand rejection means re-typing the campaign you were preparing in parallel. Here, the campaign draft survives a brand rejection.
Validation after payment — the linear flow discovers a malformed EIN or a too-short sample message one paid retry cycle later. The wizard validates each field on every save and lints the saved draft before any registration fee is charged.
An invisible dependency — a campaign submission needs the brand id minted by the brand submission. The wizard fills brand_id in from the brand outcome; you never type it.

All wizard endpoints live under /api/v1/compliance/10dlc/wizard. Authenticate with your API key, exactly as for the brand and campaign endpoints.

Roles and rate limits

Reads (GET /wizard, GET /wizard/draft) — any authenticated role on the organization.
Writes (PUT /wizard/draft, DELETE /wizard/draft, POST /wizard/phone/send, POST /wizard/phone/confirm, POST /wizard/preflight, POST /wizard/submit) — owner or admin role.
Write profile: 10 requests per minute, matching the legacy brand/campaign endpoints. Wizard preflight: 30 requests per minute, matching the ad-hoc preflight endpoint.

GET `/10dlc/wizard` — progress payload

Returns the computed progress object the dashboard uses for its “Continue where you left off” banner. Always 200 OK — a fresh organization gets the empty-draft shape with state: "not_started".

curl https://api.orbit.devotel.io/api/v1/compliance/10dlc/wizard \
  -H "X-API-Key: dv_live_sk_your_key_here"

Response:

{
  "data": {
    "state": "in_progress",
    "current_step": "campaign",
    "brand": {
      "completed_fields": 10,
      "total_fields": 10,
      "missing_fields": []
    },
    "campaign": {
      "completed_fields": 4,
      "total_fields": 6,
      "missing_fields": ["message_flow", "optout_message"]
    },
    "next_action": "fill_campaign"
  },
  "meta": {
    "request_id": "req_wiz001",
    "timestamp": "2026-09-02T10:00:00Z"
  }
}

state is one of not_started, in_progress, brand_pending, campaign_pending, ready, rejected. current_step is brand, campaign, or review. next_action is a machine-readable hint: fill_brand, fill_campaign, review_and_submit, amend_brand, amend_campaign, or done. When the brand or campaign has been submitted, the response also carries brand_id, campaign_id, and any upstream rejection reason. GET /10dlc/wizard/draft returns the full saved draft (brand fields, campaign fields, current step) for form prefill.

PUT `/10dlc/wizard/draft` — partial save

Saves any subset of brand and/or campaign fields. Every field is optional — you only validate the fields you send, and the rest keep their previously saved values. current_step updates separately so a resume lands on the right screen.

curl -X PUT https://api.orbit.devotel.io/api/v1/compliance/10dlc/wizard/draft \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": {
      "entity_type": "PRIVATE_PROFIT",
      "display_name": "Acme Corp",
      "company_name": "Acme Corporation Inc.",
      "email": "compliance@acme.com"
    },
    "current_step": "brand"
  }'

A save that fails validation returns 422 and leaves the persisted draft untouched — the previously saved state survives. Brand fields: entity_type, display_name, company_name, ein, phone, street, city, state, postal_code, country, email, website, vertical. Campaign fields: usecase, description (40–4096 characters), sample_message (1–10 messages), message_flow (min 40 characters), help_message (min 20), optout_message (min 20), is_political, cv_token.

Save after each required field if you like — each save costs under one write-rate token and the draft is the safety net. The campaign’s brand_id is never typed by hand: the wizard fills it in from the brand submission outcome.

Per-field validation rules

A PUT /wizard/draft validates only the fields you send and stores nothing on failure, so you can probe one field at a time. The rules:

Field	Rule
`brand.display_name`	1–100 characters (registry limit)
`brand.company_name`	1–100 characters
`brand.ein`	`xx-xxxxxxx` (two digits, hyphen, seven digits). Leave blank for non-US entities.
`brand.email`	A valid email address. The registry’s vetting checks it against your website domain.
`brand.website`	An `http://` or `https://` URL
`brand.country`	Two-letter ISO-3166 alpha-2 code
`campaign.description`	40–4096 characters
`campaign.sample_message`	1–10 strings, each 1–1024 characters, each non-empty after trimming
`campaign.message_flow`	At least 40 characters
`campaign.help_message`	At least 20 characters
`campaign.optout_message`	At least 20 characters
`campaign.cv_token`	20–4096 characters when present

Empty strings and whitespace-only strings are dropped on save rather than stored, so the progress counts on GET /wizard always reflect real field values.

Sole-proprietor phone verification (OTP)

US brands with entity_type: "SOLE_PROPRIETOR", and only those, substitute a verified mobile number for an EIN: TCR anchors sole-proprietor identity on a phone number the registrant proves they control. Every other US entity type must submit an EIN instead. Verify the number before submitting:

# 1. Dispatch the challenge to the draft's brand.phone
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/wizard/phone/send \
  -H "X-API-Key: dv_live_sk_your_key_here"

Response:

{
  "data": {
    "verification_id": "vf_abc123",
    "status": "pending",
    "channel": "sms",
    "expires_at": "2026-09-02T10:10:00Z"
  },
  "meta": {
    "request_id": "req_wiz002",
    "timestamp": "2026-09-02T10:00:00Z"
  }
}

# 2. Confirm the code from the SMS
curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/wizard/phone/confirm \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"code": "483921"}'

Response:

{
  "data": {
    "status": "verified",
    "phone": "+14155551234",
    "verified_at": "2026-09-02T10:04:12Z"
  },
  "meta": {
    "request_id": "req_wiz003",
    "timestamp": "2026-09-02T10:04:12Z"
  }
}

The proof is keyed to the exact phone string saved on the draft. If you edit brand.phone after verifying, the old proof no longer counts and submit fails with 422 until you run a fresh challenge against the new number. Calling /phone/send on an already-verified number returns 409 ALREADY_VERIFIED; calling /phone/confirm without a pending challenge returns 404.

POST `/10dlc/wizard/preflight` — lint the saved draft

Scores the persisted wizard draft against the known TCR rejection-pattern catalog, so the “Review & submit” screen sees findings against the exact draft it is about to submit — no chance of lint drift that the ad-hoc preflight endpoint has when it lints a hand-built payload. The request body is optional: expected_msg_per_day_per_number (for the throughput-tier rule) and brand_vetting_score (0–100) when you already hold one.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/wizard/preflight \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

The response shape — score, verdict, findings[] — is identical to the preflight linter on the registration page. As with that endpoint, a pass verdict means “no known rejection patterns matched,” not “TCR will approve.”

POST `/10dlc/wizard/submit` — atomic brand + campaign

Validates the full draft, then submits the brand and the campaign in one call. Brand vetting typically lands in 1–48 hours; the campaign follows immediately after.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/10dlc/wizard/submit \
  -H "X-API-Key: dv_live_sk_your_key_here"

Response (201 Created):

{
  "data": {
    "state": "brand_pending",
    "current_step": "review",
    "brand_id": "BXXXXXX",
    "campaign_id": "CXXXXXX",
    "next_action": "done"
  },
  "meta": {
    "request_id": "req_wiz004",
    "timestamp": "2026-09-02T10:05:00Z"
  }
}

Validation failures return 422 before anything is charged, with details.section telling you whether the missing or invalid fields are in the brand or campaign section. Failure semantics — the atomic guard:

Brand rejected upstream — no campaign is submitted. The draft is preserved with the brand rejection reason stamped, and next_action flips to amend_brand. Amend the brand fields and resubmit.
Campaign rejected upstream — the accepted brand_id is persisted, state stays at brand_pending, and the campaign rejection reason is stamped. A resubmission skips the brand stage entirely, so the brand fee is never re-charged; only the campaign pays again.
Upstream 5xx or provider unavailable — the draft is preserved verbatim and you can retry as-is.

State transitions to ready once both the brand and campaign come back APPROVED from carrier review.

Reading a rejected submission

When a submit is rejected, the wizard stamps the rejection on the draft: GET /wizard then returns state: "rejected" with next_action: "amend_brand" or "amend_campaign" and a brand_rejection_reason or campaign_rejection_reason, and GET /wizard/draft carries the same reason on the affected section. The rejection banner on the review step renders a fix card decoded from that reason. Rows the registry and the CSPs return are terse by design: a numeric code like 40016 or a hyphenated slug like EIN-MISMATCH, plus one free-text sentence, and no per-field guidance. Decoding that row by hand is slow and error-prone: operators paste the code into a search engine, wade through stale forum answers, and pay a fresh vetting fee plus 1–5 business days on the next attempt. Orbit ships a decoder catalog so you never have to do that. Every rejection reason that reaches the wizard is normalized to a fix card, in the dashboard banner and from POST /api/v1/compliance/10dlc/decode-rejection, whose full walkthrough lives in 10DLC rejections and re-vetting. Each card carries:

title and meaning — what the registry or carrier actually rejected, in plain English.
fix — exactly one concrete corrective step, the highest-probability one first. Not a list of maybes.
resubmit_allowed — the verdict that decides your next call. true: amend and resubmit the same record. false: the record is locked and the fix is a fresh registration, described below.
category — one of the stable buckets in the table below, for grouping rejections in your own tooling.
field — the wizard step the fix applies to (for example brand.ein or campaign.sample_message), which is what the banner uses to link you straight back to the field to correct.
references — public registry and carrier documentation, when one applies.

The decoder catalog

Code	Category	Fix, in short	Resubmit	Wizard step
`30883`	content	Rewrite sample messages to match the declared use case; drop SHAFT-C wording, shortener domains, and bare “click here” CTAs.	yes	`campaign.sample_message`
`30890`	content	Provide 2–5 distinct samples with real values rendered in place of placeholders; at least one must say “Reply STOP to opt out.”	yes	`campaign.sample_message`
`30898`	eligibility	Align the brand vertical with the messaging, or pick a use case that matches the brand identity.	yes	`campaign.usecase`
`40016`	identity	Fix the EIN to `NN-NNNNNNN` and make the legal company name match the IRS-registered name word for word.	yes	`brand.ein`
`40018`	identity	Use a brand email at your registered domain (not a personal inbox) and put a legal name and physical address in the website footer.	yes	`brand.website`
`40023`	identity	Correct the DUNS or GIIN, or drop the identifier and let vetting run on the EIN alone.	yes	`brand.ein`
`EIN-MISMATCH`	identity	Copy the IRS-registered legal name (form 147C or a recent return) verbatim into the brand’s company name, punctuation included.	yes	`brand.company_name`
`BRAND-DCA-FAIL`	dca	A post-approval carrier audit locked the brand. Register a fresh brand with a corrected vertical; allow about 30 days before re-registering.	no	`brand.vertical`
`INVALID-CV-TOKEN`	eligibility	Mint a fresh Campaign Verify token for the brand being registered; tokens are bound to one brand.	yes	`campaign.cv_token`
`THROUGHPUT-TIER-MISMATCH`	throughput	Request a brand re-vet (rate-limited to roughly once per quarter) or lower the declared volume to fit the current tier.	yes	`brand.ein`
`DUPLICATE-BRAND`	format	Reuse the existing brand id instead of registering a duplicate; a duplicate charges another fee and orphans the record.	no	`brand.ein`
`OPTOUT-LANGUAGE-MISSING`	content	Add “Reply STOP to opt out.” to at least one sample, and give the opt-out message both STOP and START semantics.	yes	`campaign.optout_message`
`MESSAGE-FLOW-INADEQUATE`	content	Replace the message-flow text with a specific opt-in description: where the consumer consents and what they tick, type, or agree to.	yes	`campaign.message_flow`

`resubmit_allowed`: amend versus start over

Two codes lock the record instead of asking for an amendment. BRAND-DCA-FAIL means a carrier ran a direct audit after registry approval and rejected the brand; the brand id is burned and the fix is a fresh brand registration, not an edit. DUPLICATE-BRAND means the registry already holds a brand for that EIN and display-name pair; the fix is reusing the existing brand id, and resubmitting would pay a second fee for an orphan record. Every other card lets you amend the pointed-at field and resubmit the same record. When the campaign was the rejected stage, resubmission reuses the already-approved brand id, so the brand fee is never paid twice. The full re-vet-versus-resubmit cost tradeoff, with worked examples, is in 10DLC rejections and re-vetting. The same cards reach you through POST /api/v1/compliance/10dlc/decode-rejection if you want to decode a raw code yourself, and the dashboard renders the card for any stamped rejection without an extra call.

`field`: the deep link back into the wizard

field names the exact draft field the fix applies to, as brand.<field> or campaign.<field>. The dashboard’s rejection banner uses it to place a link directly on that field, so applying the fix is a one-click jump into the right step rather than a hunt through two forms.

When a code is not in the catalog

The decoder never returns an empty card. A reason it cannot normalize still yields a full card: category unknown, a short explanation, and a fix that routes the raw rejection text to Devotel compliance support, with new codes added to the catalog as they appear. You always get a normalized card to act on, never a blank fix panel. Code spelling is normalized before lookup, so TCR-30883, Twilio Error 30883, and ein_mismatch all resolve to the same cards as 30883 and EIN-MISMATCH. When the code alone is ambiguous, the registry’s free-text reason is inspected to pick the matching card.

The wizard state machine

GET /wizard reports exactly one state; writes only ever move it forward, and DELETE /wizard/draft is the single hatch back to the start.

State	Meaning	How you get there
`not_started`	No draft saved yet	A fresh organization, or `DELETE /wizard/draft`
`in_progress`	Draft in progress, nothing submitted upstream	The first `PUT /wizard/draft`
`brand_pending`	Brand accepted upstream, campaign submitted or awaiting amendment	`POST /wizard/submit` with the brand accepted; also where a campaign rejection lands, so amending the campaign never re-pays the brand fee
`campaign_pending`	Brand approved, campaign still in carrier review	The brand is approved while the campaign review is open — at submit time or via the approval webhook
`ready`	Brand and campaign both approved	Both approval webhooks; registration complete
`rejected`	The brand was rejected upstream	`POST /wizard/submit`; the rejection reason is stamped on the draft and `next_action` becomes `amend_brand`

A draft save never moves the state backward out of brand_pending, campaign_pending, or ready; only the submit path, the approval webhooks, and DELETE /wizard/draft change it. Inside in_progress, current_step (brand, campaign, or review) tracks where you are, and next_action tells your tooling what to do next: fill_brand, fill_campaign, review_and_submit, amend_brand, amend_campaign, or done.

Resume: “Continue where you left off”

The dashboard banner is a plain rendering of GET /wizard: state picks the banner, current_step picks the screen to land on, the brand and campaign counts drive the progress ring, and next_action sets the call-to-action. Because the draft is your organization’s persisted storage, “resume” works across sessions, browsers, and devices: any authenticated teammate sees the same banner, and GET /wizard/draft prefills the forms exactly as they were saved.

DELETE `/10dlc/wizard/draft` — reset

curl -X DELETE https://api.orbit.devotel.io/api/v1/compliance/10dlc/wizard/draft \
  -H "X-API-Key: dv_live_sk_your_key_here"

Returns 204 No Content. Resets the wizard to the empty draft (state: "not_started"). This does not clear the approved brand or campaign ids on file — it only resets the wizard working state, so it is safe as post-approval cleanup or a “start over.”

Full lifecycle order

PUT /10dlc/wizard/draft — progressively fill brand + campaign.
(SOLE_PROPRIETOR only) POST /10dlc/wizard/phone/send → POST /10dlc/wizard/phone/confirm.
POST /10dlc/wizard/preflight — fix findings until the verdict passes.
POST /10dlc/wizard/submit — atomic submission.
GET /10dlc/wizard — poll state until ready (or GET /10dlc/campaigns/:id/status for the per-carrier map, as on the registration page).
DELETE /10dlc/wizard/draft — optional post-approval cleanup.

The legacy single-shot endpoints (POST /10dlc/brand, POST /10dlc/campaign) stay available for scripted pipelines. The wizard is the recommended operator flow; the direct endpoints demand a fully populated payload in one request.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

10DLC registration wizard with save-and-resume drafts

10DLC Registration Wizard

Why the wizard exists

Roles and rate limits

GET `/10dlc/wizard` — progress payload

PUT `/10dlc/wizard/draft` — partial save

Per-field validation rules

Sole-proprietor phone verification (OTP)

POST `/10dlc/wizard/preflight` — lint the saved draft

POST `/10dlc/wizard/submit` — atomic brand + campaign

Reading a rejected submission

The decoder catalog

`resubmit_allowed`: amend versus start over

`field`: the deep link back into the wizard

When a code is not in the catalog

The wizard state machine

Resume: “Continue where you left off”

DELETE `/10dlc/wizard/draft` — reset

Full lifecycle order

See also

​10DLC Registration Wizard

​Why the wizard exists

​Roles and rate limits

​GET /10dlc/wizard — progress payload

​PUT /10dlc/wizard/draft — partial save

​Per-field validation rules

​Sole-proprietor phone verification (OTP)

​POST /10dlc/wizard/preflight — lint the saved draft

​POST /10dlc/wizard/submit — atomic brand + campaign

​Reading a rejected submission

​The decoder catalog

​resubmit_allowed: amend versus start over

​field: the deep link back into the wizard

​When a code is not in the catalog

​The wizard state machine

​Resume: “Continue where you left off”

​DELETE /10dlc/wizard/draft — reset

​Full lifecycle order

​See also

10DLC Registration Wizard

Why the wizard exists

Roles and rate limits

GET `/10dlc/wizard` — progress payload

PUT `/10dlc/wizard/draft` — partial save

Per-field validation rules

Sole-proprietor phone verification (OTP)

POST `/10dlc/wizard/preflight` — lint the saved draft

POST `/10dlc/wizard/submit` — atomic brand + campaign

Reading a rejected submission

The decoder catalog

`resubmit_allowed`: amend versus start over

`field`: the deep link back into the wizard

When a code is not in the catalog

The wizard state machine

Resume: “Continue where you left off”

DELETE `/10dlc/wizard/draft` — reset

Full lifecycle order

See also