> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/api-reference/rent-numbers.md).

# Rent Numbers

Rent a temporary number for multiple incoming SMS messages.

Rentals keep a number active for a selected period and can collect multiple messages.

## Workflow

1. Query [`GET /v2/rent-numbers/catalog`](/api-reference/catalog-and-quotes.md#rental-catalog).
2. Request a live quote.
3. Create an order with a UUID v4 idempotency key.
4. Pay the hold invoice.
5. Poll with the bearer token while status is `rent_active`.
6. Read every delivered entry from `messages` until the rental completes.

## Create example

```bash
curl -sS -X POST https://api.sms4sats.com/v2/rent-numbers/orders \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 61cc8d9b-2761-48dc-8ac5-e4d3ba20e8c6' \
  -d '{"country":"US","service":"full","durationMinutes":120}'
```

Rental durations are normalized to at least two hours and then upward to a whole hour. The maximum request value is 43,200 minutes.

## Payment and cancellation

A rental hold invoice settles when the number is successfully allocated. The order then enters `rent_active`, includes an end time, and may accumulate multiple messages. Manual cancellation is available only before payment; any paid rental is not manually cancellable.

{% hint style="info" %}
For Lightning-native agents, rentals are also available through the [L402 API](/api-reference/l402.md). A paid L402 rental has no refund flow, including if allocation fails.
{% endhint %}