Guide: numbers

Español: Guía: números.

A number (DID) is registered against your account before calls and texts can use it as a sender. This page covers the registry, the launch checklist and the 10DLC step for US text messages. The shapes are in the API Reference.

Register a number you own

curl -s -X POST $API/v1/dids \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"e164": "+13125550123", "labels": ["collections"], "notes": "main outbound line"}'

• e164 is unique per account (409 conflict on a duplicate) and immutable after creation; npa is derived from +1 numbers when omitted.
• The tenant surface only creates origin: customer rows. Platform inventory is minted by the operator.
• The STIR/SHAKEN attestation you send is accepted and ignored: only the platform records it.
• Creating takes a dd_ key or an account_admin login (403 role_forbidden for a member). Reading is open to every login.
• A test key reaches no carrier: routes that buy numbers or provision carriers answer 403 test_environment.

Read health and finish the launch checklist

Goal	Endpoint
List / fetch numbers	GET /v1/dids, GET /v1/dids/{id}
Change status (active, quarantine, retired) or metadata	PATCH /v1/dids/{id}
Retire (rows never delete)	DELETE /v1/dids/{id}
Health computed from the CDR	GET /v1/dids/{id}/health
The launch checklist and its manual steps	GET /v1/dids/{id}/launch-checklist, POST /v1/dids/{id}/launch-checklist/{step}/confirmations
Carrier tickets	GET / POST /v1/dids/{id}/carrier-tickets

A number in quarantine is not dialable (422 number_quarantined).

US text messages: brand and campaign (10DLC)

A text from a US local number leaves only through a number assigned to an approved campaign:

1. Register a brand — POST /v1/messaging/brands — and wait until its status is approved (POST …/brands/{id}/refresh re-reads it).
2. Register a campaign for that brand — POST /v1/messaging/campaigns with brand_id, use_case, description, message_flow and sample_messages (409 brand_not_approved otherwise).
3. Assign the number — POST /v1/messaging/campaigns/{id}/numbers.

Until then POST /v1/sms/messages answers 422 sms_10dlc_campaign_required with zero provider calls. Toll-free senders and regions other than us are not gated by 10DLC. The provider's first-month campaign fee is loaded to your balance at cost as a messaging_fee line.

Numbers in the sandbox

The sandbox does not use your numbers: its four destinations are fixed — see limits and test numbers.