Rentals

A rental holds a number for a fixed duration instead of a single verification. Rentals are reachable with a normal API key — the same x-api-key you use for verifications, including one minted through x402. Base path: https://virtualsms.io/api/v1/rentals

Two rental types

`rental_type`	What you get
`service`	The number is locked to one service you choose
`full`	Full access to the number for any service

Catalogue (public, no key needed)

Method	Path	Returns
`GET`	`/api/v1/rentals/available`	Countries that currently have rentals, with per-duration pricing
`GET`	`/api/v1/rentals/services`	Services available in one country for one duration
`GET`	`/api/v1/rentals/price`	Price for one service + country + duration
`GET`	`/api/v1/rentals/pricing`	The full active rental price list

GET /api/v1/rentals/available

Optional query params: country, service, type (service | full), provider, duration_hours.

{
  "countries": [
    {
      "country_code": "DE",
      "country_name": "Germany",
      "flag": "🇩🇪",
      "availability": "medium",
      "pricing": {
        "service": [ { "duration_hours": 24, "duration_label": "1 Day", "price": 2.50 } ],
        "full": [ { "duration_hours": 168, "duration_label": "7 Days", "price": 19.99 } ]
      }
    }
  ],
  "total_availability": "high",
  "full_access_countries": [
    {
      "country_code": "DE",
      "country_name": "Germany",
      "flag": "🇩🇪",
      "availability": "medium",
      "pricing": { "24": 9.99, "168": 49.99 }
    }
  ]
}

Callers without an API key get banded availability (availability, total_availability). Callers presenting a valid API key get exact counts in available_count and total_available instead. Pass your key if you need to size an order programmatically.

GET /api/v1/rentals/services

country_code (ISO alpha-2) or country_id is required; duration defaults to 24.

curl "https://virtualsms.io/api/v1/rentals/services?country_code=DE&duration=24"

Returns an array of { service_id, service_name, physical_count, our_price, popular, icon_url }, where physical_count is an availability indicator for that service.

GET /api/v1/rentals/price

service and duration (integer hours) are required, plus country_code (preferred) or the legacy numeric country.

{ "price": 4.50, "duration_hours": 24 }

GET /api/v1/rentals/pricing

Takes no parameters. Returns the active price list as an array of { rental_type, duration_hours, duration_label, base_price, country_code, service_id }.

Create a rental

authenticated

Body field	Type	Required
`country`	string	yes
`rental_type`	string	yes — `service` or `full`
`duration_hours`	integer	yes — must be greater than 0
`service`	string	yes when `rental_type` is `service`
`auto_renew`	boolean	no

curl -X POST https://virtualsms.io/api/v1/rentals \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country": "DE", "rental_type": "service", "service": "wa", "duration_hours": 24}'

{
  "success": true,
  "rental_id": "c1b7e0a2-9d34-4f68-8b15-2a7c6e40f931",
  "phone_number": "+491701234567",
  "rental_type": "service",
  "service": "wa",
  "duration": "24h",
  "price": 4.50,
  "started_at": "2026-09-07T12:00:00Z",
  "expires_at": "2026-09-08T12:00:00Z",
  "auto_renew": false,
  "status": "active",
  "provider": "local"
}

provider is either local or network — which pool the number came from. Nothing more specific is ever returned.

Errors

Status	Meaning
`400`	Missing `country` / `rental_type` / `duration_hours`, missing `service` on a service rental, or an unknown `rental_type`
`402`	Insufficient balance — body carries `required` and `current`
`404`	No available numbers for rental in this country
`409`	The requested configuration is unavailable

List your rentals

authenticated

Optional ?status= — defaults to active, pass all for every status. Returns an array of

{ id, phone_number, rental_type, service_id, duration_hours, started_at, expires_at, price, auto_renew, status, sms_received, sms_forwarded, last_sms_at, provider }

Read the SMS

authenticated

{
  "rental_id": "c1b7e0a2-9d34-4f68-8b15-2a7c6e40f931",
  "phone_number": "+491701234567",
  "status": "active",
  "messages": [
    {
      "id": "5c0e1f8a-31b7-42d0-9e6a-8f4b0c72a115",
      "sender": "WhatsApp",
      "message": "Your code is 123456",
      "service_detected": "wa",
      "received_at": "2026-09-07T12:05:00Z",
      "delivery_method": "sms",
      "event_type": "sms"
    }
  ],
  "count": 1
}

Voice events appear in the same list with event_type: "voice" and additional status, extracted_code, duration_sec and caller_id fields. Newest first, capped at 100 messages.

Cancel — full refund inside the window

authenticated

No request body.

{ "success": true, "rental_id": "c1b7e0a2-...", "refund": 4.50, "status": "cancelled" }

Cancellation is allowed while both of these hold:

within 20 minutes of the rental starting, and
no SMS has arrived yet on the number.

The refund covers the rental price plus any extension you bought inside the same window.

A network service rental additionally cannot be cancelled in its first 2 minutes — the call returns 400 until the rental is two minutes old. So the practical cancel window for those is roughly minute 2 to minute 20.

Status	Meaning
`400`	Outside the 20-minute window, inside the 2-minute floor, or an SMS already arrived
`404`	Rental not found or already cancelled
`502` / `503`	Cancellation temporarily unavailable — retry shortly

Swap — a new number, same rental

authenticated

No request body. Replaces the number without ending the rental; expires_at is unchanged.

{
  "success": true,
  "rental_id": "c1b7e0a2-...",
  "phone_number": "+491709999999",
  "expires_at": "2026-09-08T12:00:00Z"
}

Eligibility is narrow — all of these must hold:

rental_type is service and provider is network
no SMS has arrived yet
the rental is between 2:00 and 19:30 old

Status	Meaning
`409`	Not eligible, or outside the 2:00–19:30 window
`503`	No replacement number available (`"code": "swap_no_stock"`) or swap temporarily unavailable
`502`	The new number is live but releasing the old one is still retrying — `"code": "swap_release_pending"`, and `swapped` is `true`. Your new number works; no action needed

Extend

authenticated

Body: {"duration_hours": 24} — required and non-zero.

{
  "success": true,
  "rental_id": "c1b7e0a2-...",
  "new_expires_at": "2026-09-09T12:00:00Z",
  "price": 2.00
}

network rentals accept only 24, 72 or 168 hours; anything else returns 400. A 402 carries required and current. If the extension fails upstream you get 502 and are not charged.

Release early — partial refund, local rentals only

authenticated

{
  "success": true,
  "rental_id": "c1b7e0a2-...",
  "status": "completed",
  "hours_used": "3.25",
  "refund": 2.10,
  "message": "Rental released successfully. Refund added to store credit."
}

Only rentals with provider: "local" can be released early. A network rental returns 400 and runs to its natural expiry — past the 20-minute cancel window there is no early exit for it.
The rental must be at least 2 hours old.
The refund is pro-rata: the unused portion of the price, minus a 10% fee. For a full rental, any services already used are deducted instead of elapsed time when that is larger. The result is never negative and never exceeds what you paid.

Report a problem

authenticated

Body field	Required	Notes
`service_id`	on `service` rentals	Must match the rental’s service
`issue_type`	no	`no_sms` (default), `wrong_service`, `banned`, `other`
`description`	no	Free text

{
  "success": true,
  "issue_id": "0a3f7c15-6b28-4e9d-91f0-3c85b4d27e60",
  "manual_review": true,
  "message": "Report received. Our team will review and follow up."
}

Reporting queues a human review — it does not issue an automatic refund or replacement. Reporting the same rental twice returns 409 with the existing issue_id.

Overview

Account

Numbers & SMS

Rentals & Proxies

Legacy API

Two rental types

Catalogue (public, no key needed)

GET /api/v1/rentals/available

GET /api/v1/rentals/services

GET /api/v1/rentals/price

GET /api/v1/rentals/pricing

Create a rental

Errors

List your rentals

Read the SMS

Cancel — full refund inside the window

Swap — a new number, same rental

Extend

Release early — partial refund, local rentals only

Report a problem

​Two rental types

​Catalogue (public, no key needed)

​GET /api/v1/rentals/available

​GET /api/v1/rentals/services

​GET /api/v1/rentals/price

​GET /api/v1/rentals/pricing

​Create a rental

​Errors

​List your rentals

​Read the SMS

​Cancel — full refund inside the window

​Swap — a new number, same rental

​Extend

​Release early — partial refund, local rentals only

​Report a problem

Two rental types

Catalogue (public, no key needed)

GET /api/v1/rentals/available

GET /api/v1/rentals/services

GET /api/v1/rentals/price

GET /api/v1/rentals/pricing

Create a rental

Errors

List your rentals

Read the SMS

Cancel — full refund inside the window

Swap — a new number, same rental

Extend

Release early — partial refund, local rentals only

Report a problem