Number Rental API
Rent a phone number for a fixed period and read every SMS it receives, through the legacy-compatible handler_api.php endpoint.
How it works
Each request is a GET to /stubs/handler_api.php with api_key and action. Rental actions answer with JSON, both on success and on error.
Only API key authentication is accepted for rental actions. Web session tokens receive WRONG_ACTION.
Prices are the same as in the web panel and are charged in USD from your wallet.
Actions
| Action | Parameters | What it does |
|---|---|---|
getRentServicesAndCountries | country, rent_time | Priced rental offers for one country and duration. services.{code}.cost is the price, quant is the available stock. |
getRentNumber | service, country, rent_time | Rents a number and charges the wallet. Returns phone.id, phone.number and phone.endDate. |
getRentStatus | id, page, size | SMS received by the rented number, newest first. Optional page (starts at 0) and size. |
setRentStatus | id, status (1 | 2) | status=1 finishes the rental early without a refund. status=2 cancels it; the full charge is refunded only if no SMS was received. |
continueRentNumber | id, rent_time, expectedCharge | Extends an active rental by rent_time hours and charges the wallet. |
getRentList | - | Your active rentals: id and phone. |
getContinueRentPriceNumber | id, rent_time | Price of extending a rental, without charging. |
Country codes
- Rentals are open in 27 countries: AT, BE, BR, CZ, DE, EE, ES, FI, FR, GB, GE, GR, HR, ID, IT, LV, MD, MY, NL, PL, PT, RO, SE, SI, SK, UA, US. country is required to rent a number or read prices; the two-letter ISO code is recommended. Durations: 24, 72, 168 hours.
- To read this list from the API, call getRentServicesAndCountries without country: the response contains countryList (ISO codes), hours and currency, without prices or stock. For prices and stock, send country and rent_time.
- Recommended: send the ISO country code, for example country=US or country=GB. Upper and lower case both work.
- Numeric country IDs are not the same in every service. If you send a number, read it from the getCountries response with your own API key; do not copy it from another provider's list.
- Rental actions accept a numeric ID only for countries open for rental, as listed by getCountries. Any other number returns BAD_COUNTRY; if unsure, use the ISO code.
- The numbers 42 (DE), 44 (HR), 45 (SE), 47 (NL), 48 (LV), 49 (AT), 51 (TH), 55 (ES), 58 (SI), 62 (CZ), 72 (BR), 77 (FR), 90 (SK), 97 (PT), 115 (GE), 116 (GR), 128 (BE), 175 (FI), 178 (IT) are not accepted for rentals, because in other services they mean a different country. They always return BAD_COUNTRY_USE_ISO; nothing is charged and no number is rented. Send the ISO code instead, for example country=DE. For these countries, countries in the getRentServicesAndCountries response is empty.
- Our country slug is accepted as well.
- getRentServicesAndCountries returns the country's numeric ID in countries.
List countries and their codes
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getCountries"Rental offers for a country by ISO code
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries&country=US&rent_time=24"List countries open for rental
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries"Response
{"countryList":["AT","BE","BR","CZ","DE","EE","ES","FI","FR","GB","GE","GR","HR","ID","IT","LV","MD","MY","NL","PL","PT","RO","SE","SI","SK","UA","US"],"hours":[24,72,168],"currency":840}Example
Request
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentNumber&service=wa&country=US&rent_time=24"Response
{
"status": "success",
"phone": {
"id": "cm4x9k2...",
"endDate": "2026-11-02T12:00:00",
"number": "15550000001"
}
}Request
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentStatus&id=cm4x9k2..."Response
{
"status": "success",
"quantity": "1",
"values": {
"0": {
"phoneFrom": "WhatsApp",
"text": "Your code: 123456",
"service": "wa",
"date": "2026-11-01 12:05:00"
}
}
}Response details
- The rental id is a string (for example "cm4x9k2..."), not a number. Store it as text.
- Duration in hours is read from rent_time; the time parameter is accepted as well.
- If no duration is sent, the shortest available duration is used (currently 24 hours). Send rent_time explicitly when you rent or extend.
- currency is 840 (USD). cost and price are numbers in USD.
- endDate and SMS dates are UTC, without a time zone suffix.
- The url parameter is ignored: rentals do not send webhooks. Poll getRentStatus to read new SMS.
- Errors are returned as {"status":"error","message":"<CODE>"}. Authentication and rate limit errors keep the plain text format (BAD_KEY, RATE_LIMITED).
- Get a quote with getContinueRentPriceNumber before continueRentNumber. The amount charged never exceeds the last quote shown to you (valid for 10 minutes, same rental and rent_time). The optional expectedCharge (USD, for example 1.334) can only lower this ceiling, never raise it. If the price is above the ceiling, or you have no valid quote, the rental is not extended, nothing is charged and a new quote is returned: WRONG_CHARGE with the amount in price. Retry with the new quote.
- A rental can be extended only after its free cancellation window (the first 20 minutes) has ended; before that continueRentNumber returns CONTINUE_TOO_EARLY and nothing is charged.
Cancellation window
Cancellation is refused during the first 2 minutes of a rental (CANT_CANCEL).
Free cancellation is possible up to 20 minutes after the rental starts. After that window the cancellation is refused, usually with CANT_CANCEL (in rare cases TEMPORARILY_UNAVAILABLE); use status=1 to finish instead.
A cancelled rental is refunded in full only if it received no SMS.
Timeouts and retries
getRentNumber is not idempotent: do not retry it after a timeout. Call getRentList first; if you find a rental you do not need, cancel it between minute 2 and minute 20 for a full refund (no SMS received).
Limits
New rentals are limited per API key per UTC day (extensions are not counted): at most 50 rentals per key. Above it: RENT_LIMIT.
getRentNumber and continueRentNumber also count toward the daily API purchase quota of the key.
These actions are available for all API keys on your account.
Error codes
{ "status": "error", "message": "NO_BALANCE" }NO_ | Not enough wallet balance. |
NO_ | No number available for this service, country and duration right now. |
BAD_ | Missing or unsupported service code. |
BAD_ | Missing, unknown or unavailable country (use the ISO code). |
BAD_ | Numeric country ID not accepted for rentals (it means a different country in other services). Use the ISO code; nothing is charged. The affected numbers are listed in the Country codes section. The response also contains a readable description. |
BAD_ | Duration not offered. |
NO_ | The id parameter is missing. |
INVALID_ | No rental with this id on your account. |
INCORECT_ | setRentStatus status must be 1 or 2. |
CANT_ | Cancellation not allowed now (during the first 2 minutes, or after the free window of up to 20 minutes). |
ALREADY_ | The rental has already finished. |
ALREADY_ | The rental has already been cancelled. |
STATUS_ | The rental is active but no SMS has arrived yet. |
STATUS_ | The rental was cancelled. |
STATUS_ | The rental has finished or expired. |
RENT_ | Daily rental limit for this API key reached. |
TEMPORARILY_ | Temporary problem. For getRentNumber and continueRentNumber nothing was charged or the charge was refunded. For a cancellation the result may be unknown: check the rental with getRentStatus before retrying. |
WRONG_ | continueRentNumber: the price is above your ceiling (the last quote shown to you, valid for 10 minutes, lowered by expectedCharge), or you have no valid quote. Not extended, nothing was charged. The new quote is in price; retry with it. |
CONTINUE_ | continueRentNumber: extension is not possible during the first 20 minutes of a rental (the free cancellation window). Nothing was charged; try again after that. getContinueRentPriceNumber still works. |
ERROR_ | Unexpected server error. |
REST API
The same operations are available for all API keys as JSON endpoints under /api/v1/rentals (send the key in the x-api-key header). The daily rental limit per key is shared with the actions above; above it the REST API answers 429 with reason rent_daily_cap.
curl -X POST "https://smsbulk.net/api/v1/rentals" \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "serviceCode": "wa", "countryIso": "US", "durationHours": 24 }'Extensions: get a quote with GET /api/v1/rentals/{id}/extend-price first, then call POST /api/v1/rentals/{id}/extend. The amount charged never exceeds the last quote shown to you (valid for 10 minutes, same rental and duration). The optional expectedCharge (USD as a string, for example "1.334") can only lower this ceiling, never raise it. If the price is above the ceiling, or you have no valid quote, the rental is not extended, nothing is charged and the API answers 409 PRICE_CHANGED with the new quote in currentCharge. Retry with the new quote.
During the first 20 minutes of a rental (the free cancellation window) POST /api/v1/rentals/{id}/extend answers 409 RENTAL_EXTEND_TOO_EARLY; the body contains extendAllowedFrom (ISO time), the moment from which the extension is accepted. Nothing is charged, and quotes stay available.