Every number belongs to one account. Scope numbers (consent also accepts messaging).

​
Sandbox: simulated numbers

In a sandbox project, POST /v1/numbers with just an account_id returns a simulated number: a fictional +1 555 number, active at once, that never reaches a carrier and is never billed. Texts you send from it are recorded with status simulated; nothing is delivered. To test the inbound side, play a text arriving:
It behaves like a real carrier text: STOP, START and HELP are handled, anything else is kept and sent to your webhooks as message.received, and it counts as the person texting first.

​
Live: real numbers

Pick a number from /v1/numbers/available and POST /v1/numbers with its e164. Buying real numbers needs a paid plan with a card on file (403 plan_required otherwise), and a project under its monthly spend cap (402 spend_cap_reached otherwise). Each number is billed per month while you hold it (meters number_local_month / number_tollfree_month); see Usage. Bringing an existing number in (porting) isn’t available through the API yet; buy a new number, or contact us to port one. Calls work as soon as a number is bought. Texting in the US starts when its carrier registration is approved; until then sms_state is pending_registration and sends are refused with sms_not_active.

​
Carrier registration (US texting)

US carriers require every business that texts to register. Submit the end customer’s business details, not yours:
Local numbers register for 10DLC, toll-free numbers for toll-free verification. The carrier message flow is generated for you with one opt-in path: people text the number first after seeing it on a public opt-in page. optInPageUrl is your page (it must show the number, say that texting it means agreeing to replies, and give STOP and HELP); leave it out and Allternit hosts one at https://api.allternit.com/sms/{id}. For a person without an EIN, send entityType: "SOLE_PROPRIETOR" with contactFirstName, contactLastName and mobilePhone; the carrier texts a code there, and POST /v1/numbers/{id}/registration/otp with { "pin": "123456" } verifies it (an empty body sends a new code). A refusal caused by Allternit’s carrier account (not the business) keeps the registration pending with a rejectionReason starting waiting: and is retried automatically. 10DLC is two steps at the carrier: the brand is verified first, then the campaign is reviewed; the campaign is filed automatically once the brand clears. GET …/registration refreshes the status, and every change is sent as registration.updated. Carrier review usually takes days to a few weeks; that is controlled by the carriers, not promised by us. You may text someone only if they texted the number first (or texted START after a STOP); that is the one opt-in path the carrier registration declares. You may call someone who texted or called the number first, or whose consent you recorded:
source is required (how they agreed). STOP always wins: recorded consent never lifts an opt-out (the response says "opted_out": true); only the person texting START does.