Numbers

Temporary numbers

Short-term OTP sessions. Rent a number, wait for a code, then cancel, complete, or reuse depending on the kind.

Use case

One-time verification codes

Window

5–20 minutes, by kind

Refund

Cancel while WAITING

How it works

1. Rent with a catalog code such as s1-5.
2. Enter the phone on the service you are verifying.
3. Poll the rental (or wait for a webhook) until otpCode is set.
4. Use the code. Need another? Call renew / Awake when the kind allows it.
5. If nothing arrives while WAITING, cancel for a wallet refund.

Kinds

PRPhone dayRefund: Cancel while WAITING if no code has arrived

Premium temporary number. Free reuse within 20 minutes; paid renew while the phone day is active; after the phone day, submit a renew request.

S.15–20 minutesRefund: Cancel while WAITING if no code has arrived

Active 5–20 minutes. Receive codes continuously during the window. Paid renew after expiry if the number is still available.

S.215 minutesRefund: Cancel while WAITING if no code has arrived

15-minute window. Free Awake after each code while active. Paid renew until 30 minutes from start; after that, rent a new number. Supports reusing a phone you already hold.

S.3Service TTLRefund: Cancel while WAITING if no code has arrived

US Non-VoIP. Active for the service TTL. Receive codes continuously. Paid renew after expiry if the number is still available.

S.415 minutesRefund: Cancel while WAITING if no code has arrived

15-minute window. Window ends on each code; Awake restarts the timer. Paid renew after expiry if the number is still available.

S.510–20 minutesRefund: Cancel if no code arrives

Active 10–20 minutes. Free Awake after each code while the window is still running. Cancel if no code arrives.

Status lifecycle

Status	Meaning
`WAITING`	Number is live; no OTP yet. You can cancel for a refund.
`RECEIVED`	At least one OTP arrived. Poll for more codes until expiry.
`COMPLETED`	You marked the rental done and released the number.
`CANCELLED`	Cancelled while WAITING; wallet refunded.
`EXPIRED`	The rental window ended.

Reuse & renew

S.2 / S.5 — free Awake after a code while the window is running. S.2 paid renew only until 30 minutes from start.
PR — free reuse within 20 minutes; paid renew during the phone day; after the phone day, submit a renew request in the dashboard.
S.1 / S.3 / S.4 — paid renew after expiry if the number is still available.

Always send Idempotency-Key on renew

Reusing the same key with the same body within 24 hours returns the original response instead of charging twice.

Endpoints

Catalog: GET /api/v1/services. Full Try it lives in the API reference.

GET/api/v1/rentals?sync=1

List temporary rentals

Active rentals (WAITING / RECEIVED). sync=0 skips SMS sync (faster).

Response

JSON

{
  "count": 1,
  "rentals": [{
    "id": 1042,
    "kind": "s1",
    "serviceNo": 5,
    "code": "s1-5",
    "phone": "+12025551234",
    "serviceName": "Google",
    "status": "RECEIVED",
    "codes": ["123456"],
    "otpCode": "123456",
    "secondsRemaining": 840,
    "active": true
  }]
}

GET/api/v1/rentals/{id}?sync=1

Get a temporary rental

Poll one rental — same shape as a list item. Works after expiry too. Syncs SMS while still active.

POST/api/v1/rentals

Rent a temporary number

Charges the wallet. Send Idempotency-Key for safe retries. Optional max_price, areas, carrier (S.1: tmo | vz | att), country, phone/reuse_phone (S.2 reuse).

Request

JSON

{ "code": "s1-5", "country": "US" }

Response

JSON

{
  "rental": {
    "id": 1042,
    "kind": "s1",
    "serviceNo": 5,
    "code": "s1-5",
    "phone": "+12025551234",
    "serviceName": "Google",
    "price": 0.12,
    "status": "WAITING",
    "expiresAt": "2026-05-29T12:00:00.000Z",
    "durationMinutes": 20
  }
}

POST/api/v1/rentals/{id}/cancel

Cancel a temporary rental

Cancel a WAITING rental and refund the wallet. Fails if an OTP already arrived.

POST/api/v1/rentals/{id}/done

Complete a temporary rental

Mark the rental completed and release the number.

POST/api/v1/rentals/{id}/renew

Reuse or renew

S.2/S.5: free Awake after a code while the window is running; paid renew after it ends (S.2 only until 30 minutes from start). PR: free reuse within 20 minutes; paid renew during the phone day. Send Idempotency-Key.