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 or pr-1 (Premium, US).
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. Paid renew after expiry if the number is still available.

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

Active 10 minutes. Receive codes continuously during the window. Paid renew after expiry at the same price as a new rental, if the number is still available.

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. S.5 paid renew after expiry if the number is still available.
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 / S.6 — paid renew after expiry if the number is still available. S.6 renew is charged at the same price as a new rental.

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). PR: POST { "code": "pr-1", "country": "US" } using a code from GET /api/v1/services?kind=pr.

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). S.6: continuous codes for 10 minutes; paid renew after expiry at the same price as a new rental. PR: free reuse within 20 minutes; paid renew during the phone day. After the phone day, submit a renew request in the dashboard (not this endpoint). Send Idempotency-Key.