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.

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

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 after the provider successfully allocates the number. 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.

For Lightning-native agents, rentals are also available through the L402 API. A paid L402 rental has no refund flow, including if allocation fails.