SMS registrations

US carriers require a compliance record before a number can send SMS. For a local number, the organization registers as a brand with The Campaign Registry (TCR) through the carrier, registers each messaging use case as a campaign under that brand, and links the number to one campaign; a US toll-free number instead carries its own toll-free registration. These routes create, read, update, link, and sync those records. Statuses come from the carrier and a sync route refreshes them; a rule marked “carrier” is enforced by the carrier, which answers 400 with its own message. None of these routes has a CLI equivalent. Buying the numbers themselves is on Phone numbers; the end-to-end setup is SMS and phone numbers. Verified against lua-cli 3.33.0.

Base URL and authentication

Every route sits under https://api.heylua.ai/developer/orgs/:orgId, takes Authorization: Bearer <<YOUR_API_KEY>>, and checks a telephony scope on the organization in the path: telephony:read reads records and events, telephony:write edits them, telephony:manage unlinks a number, and telephony:provision creates brands, campaigns, and registrations, syncs them, and links a number. telephony:provision is a sensitive scope: a wildcard grant never covers it, so a scoped key must hold it by name. msisdn path parameters are E.164 digits without the leading +. A field that fails validation answers 400 with message as an array of the failed rules. Keys, scopes, and the error envelope are on the REST API overview.

Brand object

string

Brand ID; use it on the plural routes.

string

Owning organization.

string

Carrier-side brand ID, once registered.

string

Carrier status: UNVERIFIED (initial), VERIFIED, VETTED_VERIFIED, ACTIVE, INACTIVE, SUSPENDED, or DELETED.

string

The submitted fields, under their request names.

mixed

Carrier-side fields (vetting, account, and date stamps), refreshed by sync.

string

Timestamps.

Campaign object

string

Campaign ID; use it on the plural routes and when linking a number.

string

Owning organization.

string

Brand the campaign belongs to.

string

Carrier-side and TCR IDs, once registered.

string

Carrier status: ACTIVE, EXPIRED, DEACTIVATED, SUSPENDED, or DELETED.

mixed

The submitted fields, under their request names.

mixed

Carrier-side fields (TCR status, traffic and renewal flags, keywords, and date stamps), refreshed by sync.

string

Timestamps.

Registration object

string

Registration ID; use it on the tfn-registrations routes.

string

Owning organization.

string

The toll-free number.

string

Carrier-side registration ID, assigned at create, DRAFT included.

string

DRAFT or SUBMITTED.

string

Carrier review status: DRAFT, PENDING_REVIEW, CARRIERS_REVIEW, REGISTERED, REJECTED, UPDATES_REQUIRED, or BLOCKED.

string

Set when numberStatus is REJECTED.

object

The submitted sections.

string

The submitted values.

string

Timestamps.

Endpoints

Brand routes come first, then campaigns, the number link, and toll-free registrations. The singular /10dlc/brand and /10dlc/campaign routes are deprecated aliases that resolve to the organization’s most recent non-terminal brand or campaign; the plural routes address a record by ID and allow several per organization.

POST /developer/orgs/:orgId/10dlc/brand

Registers the organization’s brand with TCR through the carrier. Scope telephony:provision.

string

required

SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, or GOVERNMENT.

string

required

Brand name shown to recipients; at most 100 characters.

string

required

Legal company name; at most 100 characters.

string

required

EIN or tax ID; at most 50 characters.

string

required

One of REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY, COMMUNICATION.

string

required

Contact number in E.164 digits without +; at most 20 characters.

string

required

Contact email; at most 100 characters.

string

required

At most 100 characters each.

string

required

At most 20 characters.

string

required

At most 10 characters.

string

required

ISO 3166-1 alpha-2 code, 2 characters.

string

URL; at most 100 characters.

string

Carrier: required for SOLE_PROPRIETOR. At most 50, 50, and 20 characters.

string

Carrier: required for PUBLIC_PROFIT. At most 10, 50, and 100 characters.

Response 201 with the brand object.

GET /developer/orgs/:orgId/10dlc/brands

Lists the organization’s brands as Brand[]. Scope telephony:read.

GET /developer/orgs/:orgId/10dlc/brands/:brandId

Returns one brand object, or 200 with an empty body when the ID is unknown. Scope telephony:read.

PATCH /developer/orgs/:orgId/10dlc/brands/:brandId

Updates mutable brand fields at the carrier and locally. Scope telephony:write. Accepts any subset of the create body except entity_type. Answers 204; 404 10DLC brand not found when the brand is unknown.

POST /developer/orgs/:orgId/10dlc/brands/:brandId/sync

Refreshes the brand’s status from the carrier and answers 200 with the updated brand object. Scope telephony:provision.

POST /developer/orgs/:orgId/10dlc/brands/:brandId/campaigns/sync-from-vonage

Imports the brand’s campaigns from the carrier and upserts local records by carrier campaign ID; safe to call repeatedly. Scope telephony:provision. Answers 200 with Campaign[] for the brand; 404 10DLC brand not found for this org or not linked to Vonage. when the brand is unknown or not yet registered.

GET /developer/orgs/:orgId/10dlc/brand

Deprecated singular alias of GET …/10dlc/brands/:brandId, resolved to the organization’s most recent non-terminal brand. Answers the brand, or 200 with an empty body when there is none. Scope telephony:read.

PATCH /developer/orgs/:orgId/10dlc/brand

Deprecated singular alias of PATCH …/10dlc/brands/:brandId, resolved to the most recent non-terminal brand. Answers 204 and is a no-op when there is none. Scope telephony:write.

POST /developer/orgs/:orgId/10dlc/brand/sync

Deprecated singular alias of POST …/10dlc/brands/:brandId/sync, resolved to the most recent non-terminal brand. Answers the brand, or 200 with an empty body when there is none. Scope telephony:provision.

POST /developer/orgs/:orgId/10dlc/campaign

Registers a messaging campaign under a brand. Scope telephony:provision. 404 10DLC brand not found for this org. Create a brand first. when no registered brand matches.

string

Brand to register under. When omitted, the most recent non-terminal brand is used, even when the organization holds several.

string

required

One of CUSTOMER_CARE, CONVERSATIONAL, MARKETING, MIXED, LOW_VOLUME, 2FA, ACCOUNT_NOTIFICATION, DELIVERY_NOTIFICATION, FRAUD_ALERT, SECURITY_ALERT, POLLING_VOTING, PUBLIC_SERVICE_ANNOUNCEMENT, HIGHER_EDUCATION, CHARITY, POLITICAL, EMERGENCY, SOCIAL.

string[]

Sub-use cases for MIXED campaigns.

string

required

What the campaign sends; 40 to 4,096 characters.

string

required

Sample message; 20 to 1,024 characters.

string

Further samples; 20 to 1,024 characters each.

string

required

Sent when a recipient subscribes, replies STOP, or replies HELP.

object

required

How recipients consent.

Show properties

string

required

Brand name as shown at opt-in.

Each { method, details, attachment? }; method is one of ONLINE_FORM, LIVE_OPERATOR, POINT_OF_SALE, TEXT_TO_JOIN, OTHER; attachment is a URL.

boolean

required

Carrier: must be true; adds the “Message and Data rates may apply” disclosure.

boolean

Optional carrier disclaimer.

string

required

ONE_TIME or RECURRING.

string

required

URLs.

boolean

default:false

Content is age-restricted; messages contain links; messages contain phone numbers.

boolean

required

Carrier: must be true to accept the 10DLC terms.

string

Overrides the brand vertical for this campaign; same values as the brand.

Response 201 with the campaign object.

GET /developer/orgs/:orgId/10dlc/campaigns

Lists the organization’s campaigns as Campaign[]. Scope telephony:read.

GET /developer/orgs/:orgId/10dlc/campaigns/:campaignId

Returns one campaign object, or 200 with an empty body when the ID is unknown. Scope telephony:read.

PATCH /developer/orgs/:orgId/10dlc/campaigns/:campaignId

Updates mutable campaign fields at the carrier and locally: description, the samples, the three messages, message_flow_details, age_gated, embedded_link, embedded_phone. Scope telephony:write. Answers 204; 404 10DLC campaign not found when the campaign is unknown.

POST /developer/orgs/:orgId/10dlc/campaigns/:campaignId/sync

Refreshes the campaign’s status from the carrier and answers 200 with the updated campaign object. Scope telephony:provision.

GET /developer/orgs/:orgId/10dlc/campaign

Deprecated singular alias of GET …/10dlc/campaigns/:campaignId, resolved to the organization’s most recent non-terminal campaign. Answers the campaign, or 200 with an empty body when there is none. Scope telephony:read.

PATCH /developer/orgs/:orgId/10dlc/campaign

Deprecated singular alias of PATCH …/10dlc/campaigns/:campaignId, resolved to the most recent non-terminal campaign. Answers 204 and is a no-op when there is none. Scope telephony:write.

POST /developer/orgs/:orgId/10dlc/campaign/sync

Deprecated singular alias of POST …/10dlc/campaigns/:campaignId/sync, resolved to the most recent non-terminal campaign. Answers the campaign, or 200 with an empty body when there is none. Scope telephony:provision.

POST /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

Links a local US number to a campaign at the carrier. Scope telephony:provision. The body is optional.

string

Campaign to link. When omitted, the most recent non-terminal campaign is used, even when there are several.

Response 200 with { linked: true, warnings: string[] }. Warnings are non-blocking, for example that the number is not yet bound to an agent. 404 10DLC campaign not found for this org when no registered campaign matches. The number is not checked locally; a number the carrier does not hold is rejected by the carrier with its own message.

DELETE /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

Removes the number’s campaign link. Scope telephony:manage. Answers 204; 404 10DLC campaign not found for this org when neither the number nor the organization has a campaign.

POST /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

Creates a registration for a toll-free number at the carrier: the business, use case, sample message, opt-in evidence, and expected volume for one US toll-free number. The carrier requires an approved registration before the number can send SMS. Save it as DRAFT to keep editing, or submit it immediately; the carrier then moves numberStatus through review. Scope telephony:provision. The number is not checked locally.

object

required

Show properties

string

required

Legal name; at most 500 characters.

object

required

{ street, city, state, postal_code, country }; state is the two-letter code for US, postal_code at most 10 characters, country ISO 3166-1 alpha-2.

string

required

URL.

object

required

{ first_name, last_name, email, phone }; phone in E.164 digits without +.

string

Trading name.

string

URLs.

string

required

One of SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT.

string

required

Carrier: one of EIN, CBN, CRN, NEQ, PROVINCIAL_NUMBER, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST-IDNR, CIF, NIF, CNPJ, UID, OTHER.

string

Tax ID value.

string

required

ISO 3166-1 alpha-2 code.

object

required

{ category, description, campaign_verify_auth_token? }; description at most 500 characters.

object

required

{ content, age_gated? }; content is a sample message of at most 1,000 characters, age_gated defaults to false.

object

required

Show properties

string

required

One of Online (website, Mobile app/browser), Text-to-join, Point of sale, Other.

string

At most 494 characters.

object[]

required

Each { url }: a screenshot of the opt-in flow.

string[]

Opt-in keywords, for example ["JOIN", "START"].

string

At most 160 characters each.

string

required

One of 10, 100, 1,000, 10,000, 100,000, 250,000, 500,000, 750,000, 1,000,000, 5,000,000, 10,000,000+.

string

required

Context for the reviewer; at most 350 characters.

string

default:"DRAFT"

DRAFT saves without submitting; SUBMITTED submits immediately.

Response 201 with the registration object.

GET /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

Returns the number’s registration object, refreshing its status from the carrier first, or 200 with an empty body when the number has no registration. Scope telephony:read.

PATCH /developer/orgs/:orgId/tfn-registrations/:id

Updates a registration, or submits it by setting status to SUBMITTED. Scope telephony:write. Accepts any subset of the create body; status accepts only SUBMITTED. The carrier accepts updates only while the registration is DRAFT or its number is UPDATES_REQUIRED, and answers 400 otherwise. Answers 204; 404 TFN registration not found when the registration does not belong to the organization.

GET /developer/orgs/:orgId/tfn-registrations/:id/events

Returns the carrier’s event history for the registration, newest first, as { id, status, reason?, created_at }[]. Scope telephony:read. 404 TFN registration not found.

POST /developer/orgs/:orgId/tfn-registrations/:id/sync

Refreshes the registration’s status from the carrier and answers 201 with the updated registration object, or 201 with an empty body when the ID is unknown. Scope telephony:provision.

Errors

Status	Message	Meaning
`400`	Validation messages, or a carrier message	A field failed a rule named in `message`, or the carrier refused the record; fix the field
`400`	A carrier message on a toll-free update	The carrier accepts updates only while the registration is `DRAFT` or its number is `UPDATES_REQUIRED`; check `numberStatus`
`403`	—	The key lacks the scope on this organization; `telephony:provision` must be granted by name
`404`	`10DLC brand not found for this org. Create a brand first.`	Campaign registration with no registered brand; create the brand
`404`	`10DLC brand not found`, `10DLC brand not found for this org or not linked to Vonage.`, `10DLC campaign not found`, `10DLC campaign not found for this org`, `TFN registration not found`	Unknown record on update, sync, link, unlink, or events; list the records and retry

Example

Link a purchased local number to a registered campaign. No CLI command does this, so there is no CLI tab.

const response = await fetch(
  'https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/phone-numbers/12025550100/10dlc/link',
  {
    method: 'POST',
    headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
    body: JSON.stringify({ campaignId: '<<CAMPAIGN_ID>>' }),
  },
);
if (!response.ok) throw new Error(`Link failed: ${response.status} ${await response.text()}`);
const result: { linked: boolean; warnings: string[] } = await response.json();
for (const warning of result.warnings) console.warn(warning);

curl -X POST "https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/phone-numbers/12025550100/10dlc/link" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "campaignId": "<<CAMPAIGN_ID>>" }'

SDK

CLI

REST API

SMS registrations

Base URL and authentication

Brand object

Campaign object

Registration object

Endpoints

POST /developer/orgs/:orgId/10dlc/brand

GET /developer/orgs/:orgId/10dlc/brands

GET /developer/orgs/:orgId/10dlc/brands/:brandId

PATCH /developer/orgs/:orgId/10dlc/brands/:brandId

POST /developer/orgs/:orgId/10dlc/brands/:brandId/sync

POST /developer/orgs/:orgId/10dlc/brands/:brandId/campaigns/sync-from-vonage

GET /developer/orgs/:orgId/10dlc/brand

PATCH /developer/orgs/:orgId/10dlc/brand

POST /developer/orgs/:orgId/10dlc/brand/sync

POST /developer/orgs/:orgId/10dlc/campaign

GET /developer/orgs/:orgId/10dlc/campaigns

GET /developer/orgs/:orgId/10dlc/campaigns/:campaignId

PATCH /developer/orgs/:orgId/10dlc/campaigns/:campaignId

POST /developer/orgs/:orgId/10dlc/campaigns/:campaignId/sync

GET /developer/orgs/:orgId/10dlc/campaign

PATCH /developer/orgs/:orgId/10dlc/campaign

POST /developer/orgs/:orgId/10dlc/campaign/sync

POST /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

DELETE /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

POST /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

GET /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

PATCH /developer/orgs/:orgId/tfn-registrations/:id

GET /developer/orgs/:orgId/tfn-registrations/:id/events

POST /developer/orgs/:orgId/tfn-registrations/:id/sync

Errors

Example

See also

​Base URL and authentication

​Brand object

​Campaign object

​Registration object

​Endpoints

​POST /developer/orgs/:orgId/10dlc/brand

​GET /developer/orgs/:orgId/10dlc/brands

​GET /developer/orgs/:orgId/10dlc/brands/:brandId

​PATCH /developer/orgs/:orgId/10dlc/brands/:brandId

​POST /developer/orgs/:orgId/10dlc/brands/:brandId/sync

​POST /developer/orgs/:orgId/10dlc/brands/:brandId/campaigns/sync-from-vonage

​GET /developer/orgs/:orgId/10dlc/brand

​PATCH /developer/orgs/:orgId/10dlc/brand

​POST /developer/orgs/:orgId/10dlc/brand/sync

​POST /developer/orgs/:orgId/10dlc/campaign

​GET /developer/orgs/:orgId/10dlc/campaigns

​GET /developer/orgs/:orgId/10dlc/campaigns/:campaignId

​PATCH /developer/orgs/:orgId/10dlc/campaigns/:campaignId

​POST /developer/orgs/:orgId/10dlc/campaigns/:campaignId/sync

​GET /developer/orgs/:orgId/10dlc/campaign

​PATCH /developer/orgs/:orgId/10dlc/campaign

​POST /developer/orgs/:orgId/10dlc/campaign/sync

​POST /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

​DELETE /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

​POST /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

​GET /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

​PATCH /developer/orgs/:orgId/tfn-registrations/:id

​GET /developer/orgs/:orgId/tfn-registrations/:id/events

​POST /developer/orgs/:orgId/tfn-registrations/:id/sync

​Errors

​Example

​See also

Base URL and authentication

Brand object

Campaign object

Registration object

Endpoints

POST /developer/orgs/:orgId/10dlc/brand

GET /developer/orgs/:orgId/10dlc/brands

GET /developer/orgs/:orgId/10dlc/brands/:brandId

PATCH /developer/orgs/:orgId/10dlc/brands/:brandId

POST /developer/orgs/:orgId/10dlc/brands/:brandId/sync

POST /developer/orgs/:orgId/10dlc/brands/:brandId/campaigns/sync-from-vonage

GET /developer/orgs/:orgId/10dlc/brand

PATCH /developer/orgs/:orgId/10dlc/brand

POST /developer/orgs/:orgId/10dlc/brand/sync

POST /developer/orgs/:orgId/10dlc/campaign

GET /developer/orgs/:orgId/10dlc/campaigns

GET /developer/orgs/:orgId/10dlc/campaigns/:campaignId

PATCH /developer/orgs/:orgId/10dlc/campaigns/:campaignId

POST /developer/orgs/:orgId/10dlc/campaigns/:campaignId/sync

GET /developer/orgs/:orgId/10dlc/campaign

PATCH /developer/orgs/:orgId/10dlc/campaign

POST /developer/orgs/:orgId/10dlc/campaign/sync

POST /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

DELETE /developer/orgs/:orgId/phone-numbers/:msisdn/10dlc/link

POST /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

GET /developer/orgs/:orgId/phone-numbers/:msisdn/tfn

PATCH /developer/orgs/:orgId/tfn-registrations/:id

GET /developer/orgs/:orgId/tfn-registrations/:id/events

POST /developer/orgs/:orgId/tfn-registrations/:id/sync

Errors

Example

See also