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

# Numbers and US registration

> Phone numbers for texting are provisioned for you and rented by the month. Texting US numbers needs a one-time business registration.

Texting runs on Pramaan's account: there is nothing to connect. You need a number to send from,
and Pramaan gets it for you.

## Send a text

```ts theme={null}
const { status, from, ref } = await pramaan.run("sms.send", {
  to: "+447700900555",
  body: "Your order has shipped.",
});
```

* If you have a number in the destination's country, it is used.
* If you have none, one is provisioned there first and the text is sent from it. `from` in the
  result tells you which number was used.
* Pass `from` to choose one of your numbers yourself.
* `ref` goes to `sms.status` to read the delivery status.

## Numbers are rented by the month

| Call | What it does |
| - | - |
| `phone.number.provision` | Get a number in a `country`, optionally in an `areaCode` or of a `type` (`local`, `mobile`, `toll_free`). |
| `phone.numbers.list` | Your numbers and what each can do. |
| `phone.number.release` | Give a number back. Its charge stops. This cannot be undone. |

* A number's first month is charged the moment it is bought, whether you asked for it with
  `phone.number.provision` or `sms.send` got it for you, and even if the rest of that call then
  fails: the number is yours. It then renews every month from your credit, on the same day.
* Number charges and registration fees do not count toward your daily spend cap. They only need
  enough credit.
* Retrying `phone.number.provision` with the same `Idempotency-Key` never buys a second number.
* If a renewal cannot be paid, the number stops sending and you get a `rental.past_due` event.
  Top up within 7 days and it carries on. After 7 days it is released and you get
  `rental.released`.
* Some countries only hand out numbers after identity or address checks. Those cannot be
  provisioned automatically yet; the call returns a clear `invalid_request`.

Your numbers are listed under **Numbers** in the dashboard.

## United States: register first

US carriers only deliver business texts from a registered business and campaign. Until your
registration is approved, `sms.send` to a US number returns `invalid_request` and nothing is
sent.

1. Call `sms.registration.submit` with your business details (legal name, tax id, address, a
   contact person) and your campaign (what you send, how people opted in, two to five sample
   messages, and public links to your privacy policy and terms: `privacyPolicyUrl` and
   `termsUrl`; carriers reject a campaign without them). This files the business.
2. Poll `sms.registration.status`. Reviews take from minutes to a few days.
3. When the status is `brand_approved`, call `sms.registration.submit` again with the same
   details and a **new** `Idempotency-Key`. This files the campaign. (Reusing the first call's
   key only replays its answer.)
4. When the status is `approved`, you can text US numbers.

| Status | Meaning |
| - | - |
| `not_submitted` | Nothing filed yet. |
| `brand_pending` | Your business is being reviewed. |
| `brand_approved` | Call `sms.registration.submit` again to file the campaign. |
| `campaign_pending` | Your campaign is being reviewed. |
| `approved` | You can text US numbers. |
| `failed` | Rejected. Correct the details and submit again. |

The carriers charge for registration: a fee when the business is filed, a fee when the campaign
is filed, and a monthly campaign fee. Each fee is charged once, when that filing is made; the
campaign's first month is charged when the campaign is filed, and it then renews like a number
does. The call itself costs the minimum call price, also when there is nothing to file. If your
credit cannot cover a fee, or a number's first month, the call returns `402 spend_cap_reached`
and nothing is filed or bought.

If the campaign's monthly fee cannot be paid, you get `rental.past_due` and US texts keep going
for 7 days. After that the campaign is withdrawn, you get `rental.released`, and texts to US
numbers are refused again until you submit the registration again (your business stays
registered; only the campaign is filed anew).

Not supported yet: sole-proprietor registration, toll-free verification and short codes.

## Delivery and replies

Subscribe a [webhook endpoint](https://docs.pramaan.dev/guides/webhooks.md) to:

| Event | When |
| - | - |
| `sms.message.delivered` | The carrier confirmed delivery. `data.ref` is the `ref` from `sms.send`. |
| `sms.message.failed` | Delivery failed. `data.errorCode` has the carrier's numeric code when there is one. |
| `sms.message.received` | Someone texted one of your numbers: `from`, `to`, `text`. |

## Limits

Each account can send 200 texts a day by default. Past that, `sms.send` returns
`429 rate_limited` until the next day (UTC). Ask us if you need more.


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