> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simjuno.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simjuno.com/_mcp/server.

# SMS numbers

> Rent phone numbers that receive SMS and forward them to an eSIM.

SimJuno eSIMs are data-only: they have no phone number of their own. An SMS number is a phone number you rent separately for a set number of days. SMS sent to it are kept in its inbox and, when it is linked to an eSIM, forwarded to that eSIM as an SMS. Use it to receive one-time verification codes.

An SMS number can only receive SMS. It cannot send SMS or make or receive calls.

## Which eSIMs can receive forwarded SMS

A number can be linked to an eSIM you ordered whose plan has `smsStatus` `1` or `2` (shown on `GET /esim/destination/{slug}` and `GET /esim/package/{slug}`) and that has not expired. Plans with `smsStatus` `0` cannot receive SMS. You can rent a number without linking it and read its SMS through the API instead.

## Flow

1. **API** — Call `GET /sms-number/offers` to list the numbers on sale. Each offer has a `product_id` and the rental lengths (`days`) with their `price`. The list is empty while no numbers are on sale. Prices use the same factor of 10,000 as your balance, and the account `discount_percent` does not apply to SMS numbers.
2. **API** — Call `POST /sms-number/order` with the `product_id`, `days`, a unique reseller `transaction_id` and, optionally, the `esim_id` to forward to. The price is debited from your reseller wallet and the rented number is returned straight away. To safely retry, reuse the same `transaction_id` with the same `product_id` and `days`. If no number can be supplied, you are not charged and must use a new `transaction_id` to try again.
3. **API** — To link, change or remove the eSIM later, call `PUT /sms-number/{id}/esim` with an `esim_id`, or `null` to keep new SMS in the inbox only.
4. **Webhook/API** — Wait for an [`SMS_RECEIVED` webhook](/webhook#sms-received), or poll `GET /sms-number/{id}/messages`. Each message's `forward_status` shows whether it reached the eSIM.
5. **API** — Call `GET /sms-number` to list your numbers and `GET /sms-number/{id}` for one of them. A number stops receiving SMS at `expires_at`.

## Refunds

Call `POST /sms-number/{id}/refund` to return the price to your reseller wallet. This is only possible before `refundable_until` and before the number has received any SMS. `refundable_until` is `null` for numbers that cannot be refunded.