Number Rental API

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.

Rental actions are available for all API keys, with a daily limit per key (see Limits).

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

ActionParametersWhat it does
getRentServicesAndCountriescountry, rent_timePriced rental offers for one country and duration. services.{code}.cost is the price, quant is the available stock.
getRentNumberservice, country, rent_timeRents a number and charges the wallet. Returns phone.id, phone.number and phone.endDate.
getRentStatusid, page, sizeSMS received by the rented number, newest first. Optional page (starts at 0) and size.
setRentStatusid, 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.
continueRentNumberid, rent_time, expectedChargeExtends an active rental by rent_time hours and charges the wallet.
getRentList-Your active rentals: id and phone.
getContinueRentPriceNumberid, rent_timePrice 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_BALANCENot enough wallet balance.
NO_NUMBERSNo number available for this service, country and duration right now.
BAD_SERVICEMissing or unsupported service code.
BAD_COUNTRYMissing, unknown or unavailable country (use the ISO code).
BAD_COUNTRY_USE_ISONumeric 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_TIMEDuration not offered.
NO_ID_RENTThe id parameter is missing.
INVALID_PHONENo rental with this id on your account.
INCORECT_STATUSsetRentStatus status must be 1 or 2.
CANT_CANCELCancellation not allowed now (during the first 2 minutes, or after the free window of up to 20 minutes).
ALREADY_FINISHThe rental has already finished.
ALREADY_CANCELThe rental has already been cancelled.
STATUS_WAIT_CODEThe rental is active but no SMS has arrived yet.
STATUS_CANCELThe rental was cancelled.
STATUS_FINISHThe rental has finished or expired.
RENT_LIMITDaily rental limit for this API key reached.
TEMPORARILY_UNAVAILABLETemporary 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_CHARGEcontinueRentNumber: 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_TOO_EARLYcontinueRentNumber: 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_SQLUnexpected 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.