Numbers

Long-term numbers

Keep the same phone for days. Lines stay active for the plan period (L.1 sleeps until you wake it). Codes arrive throughout.

Use case

Same number, many codes

Active

Full rental period

Refund

30 minutes, no code yet

How it works

1. Browse GET /api/v1/long-term/plans and copy a code such as l2-3.
2. POST /api/v1/long-term/rentals with that code.
3. For L.1, POST .../wake before you expect a code.
4. Read messages with GET .../messages.

Kinds

L.1

Plan period

Wake/sleep long-term line. POST .../wake before you expect a code. Optional US area code and bulk quantity.

L.2

Plan period

Service long-term rental. Number stays active for the full period; codes arrive continuously.

L.3

Multi-day plan

Multi-day long-term rental. Number stays active for the full period; codes arrive continuously.

Refunds

Cancel within 30 minutes of renting, and only if no code has arrived. After that window, or after the first SMS, the rental is not refundable through the API.

Create debit is atomic from your side

If rent succeeds, the wallet is charged. If the request fails with 4xx, you are not charged. Retry create with a new Idempotency-Key only when you intend a new number.

Auto-renew & extend

POST .../auto-renew toggles prepaid Early Renewal while the rental is still active — it charges or refunds the wallet. POST .../renew extends or reactivates when the kind supports it (L.2 renew; L.1 reactivation rules apply).

If auto-renew is on and the wallet cannot cover the next period, auto-renew turns off and the line expires — you are not charged for a period that did not start.

Endpoints

GET/api/v1/long-term/plans?page=1&pageSize=100&q=google

Long-term catalog

Paginated long-term catalog. Copy code (e.g. l2-3) to rent.

GET/api/v1/long-term/rentals?sync=1

List long-term rentals

Your long-term rentals. sync=0 skips remote refresh.

POST/api/v1/long-term/rentals

Rent a long-term number

L.1 supports area_code and quantity (quantity > 1 requires Idempotency-Key).

Request

JSON

{ "code": "l2-3" }

Response

JSON

{
  "rental": {
    "id": "clx...",
    "kind": "l2",
    "planNo": 3,
    "code": "l2-3",
    "serviceName": "Google",
    "phone": "+12025551234",
    "sellPrice": 5.0,
    "status": "ACTIVE",
    "lineStatus": "active",
    "refundable": true
  }
}

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

Get a long-term rental

Poll one long-term rental (id is the string from the create response).

GET/api/v1/long-term/rentals/{id}/messages?sync=1

List messages

SMS for that rental. Each message has otpCode and smsText. full=1 does a deeper sync.

Response

JSON

{
  "count": 1,
  "codeCount": 1,
  "messages": [{
    "id": "msg_...",
    "from": null,
    "to": "+12025551234",
    "smsText": "Your Google verification code is 123456",
    "otpCode": "123456",
    "receivedAt": "2026-05-29T12:00:00.000Z"
  }]
}

POST/api/v1/long-term/rentals/{id}/cancel

Cancel / refund

Request a refund within 30 minutes if no code has arrived.

POST/api/v1/long-term/rentals/{id}/wake

Wake an L.1 line

L.1 only — wake a sleeping line before you expect a code.

POST/api/v1/long-term/rentals/{id}/auto-renew

Toggle auto-renew

Prepaid auto-renew (Early Renewal) while the rental is still active. Charges or refunds the wallet.

POST/api/v1/long-term/rentals/{id}/renew

Renew a long-term rental

Extend or reactivate when the kind supports it (L.2 renew; L.1 reactivation rules apply).