API documentation

Overview

Authentication

Send your API key as api_key in the URL of every request. Find it on your Profile page.

Rental limit

A limited number of rentals can wait for SMS at once (shown on your dashboard). Rent a number just before you need it. Contact support for a higher limit.

Fair billing

You only pay when a code arrives. Cancelled or expired rentals are refunded to your balance.

Base URL

GET or POST

https://hollysms.com/stubs/handler_api.php

All responses are plain text, for example ACCESS_BALANCE:50.30. Replace YOUR_API_KEY in the examples with your own key.

Rate limits

Action	Scope	Limit	Description
`getBalance`	action	10 / sec	Per API key.
`getNumber`	action	10 / sec	Per API key.
`getStatus, setStatus, getExtraActivation`	action	1 / 3 sec	Per API key and rental ID.
`getPrices, getPricesVerification`	action	5 / 10 sec	Per API key.

When a limit is exceeded the API responds with RATE_LIMIT_EXCEEDED.

01

Check balance

Returns your current account balance in US dollars. Useful to check that you have enough funds before renting a number.

GET /stubs/handler_api.php?action=getBalance

Parameters

Parameter	Type	Status	Description
`api_key`	string	Required	Your API key from the Profile page.
`action`	string	Required	Must be `getBalance`.

Example request

curl "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance"

const res = await fetch(
  "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance"
);
const text = await res.text();
console.log(text);

import requests

r = requests.get(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance"
)
print(r.text)

<?php
$response = file_get_contents(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance"
);
echo $response;

Responses

Response	Meaning
`ACCESS_BALANCE:50.30`	Success. Your balance is $50.30.
`BAD_KEY`	The API key is missing, wrong or the account is not active.

02

Get a number

Rents a real USA non-VoIP number for the chosen service. The response gives you the rental ID and the phone number. Use the service shortcode from the Services page (the API name column).

GET /stubs/handler_api.php?action=getNumber

Parameters

Parameter	Type	Status	Description
`api_key`	string	Required	Your API key from the Profile page.
`action`	string	Required	Must be `getNumber`.
`service`	string	Required	Service shortcode, for example `wa` for WhatsApp.
`max_price`	number	Optional	Highest price you accept, in dollars (e.g. `0.50`). If the current price is higher, the request fails with `MAX_PRICE_EXCEEDED`. The limit is inclusive. Recommended on every request — see dynamic pricing.

Example request

curl "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&max_price=1.00"

const res = await fetch(
  "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&max_price=1.00"
);
const text = await res.text();
console.log(text);

import requests

r = requests.get(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&max_price=1.00"
)
print(r.text)

<?php
$response = file_get_contents(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&max_price=1.00"
);
echo $response;

Responses

Response	Meaning
`ACCESS_NUMBER:10423:14155550142`	Success. Rental ID is 10423, number is +1 415 555 0142.
`MAX_PRICE_EXCEEDED`	The current price is higher than your `max_price`.
`NO_NUMBER_AVAILABLE`	No numbers are available for this service right now. Try again shortly.
`TOO_MANY_ACTIVE_RENTALS`	You have reached your active rental limit. Finish or cancel one first.
`NO_MONEY`	Not enough balance. Add funds.
`BAD_KEY`	The API key is missing or wrong.

03

Receive the code

Checks whether the SMS has arrived for a rental. Poll this endpoint every 3 seconds or more until you get the code, or use a webhook instead. Services marked ∞ can receive several codes — the latest one is returned.

GET /stubs/handler_api.php?action=getStatus

Parameters

Parameter	Type	Status	Description
`api_key`	string	Required	Your API key from the Profile page.
`action`	string	Required	Must be `getStatus`.
`id`	number	Required	Rental ID from the `getNumber` response.

Example request

curl "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=10423"

const res = await fetch(
  "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=10423"
);
const text = await res.text();
console.log(text);

import requests

r = requests.get(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=10423"
)
print(r.text)

<?php
$response = file_get_contents(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=10423"
);
echo $response;

Responses

Response	Meaning
`STATUS_OK:482193`	The code has arrived: 482193.
`STATUS_WAIT_CODE`	Still waiting for the SMS. Check again in a few seconds.
`NO_ACTIVATION`	No rental found with this ID (or it has already finished).

04

Finish or cancel a rental

Ends a rental. If no code was received, the full price is returned to your balance. If a code was received, the rental is marked as done and frees a slot. Please don’t rent and cancel numbers in a loop without using them — it can get your account restricted.

GET /stubs/handler_api.php?action=setStatus

Parameters

Parameter	Type	Status	Description
`api_key`	string	Required	Your API key from the Profile page.
`action`	string	Required	Must be `setStatus`.
`id`	number	Required	Rental ID from the `getNumber` response.
`status`	number	Required	`6` = done, `8` = cancel. Both refund the price if no code was received.

Example request

curl "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=10423&status=8"

const res = await fetch(
  "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=10423&status=8"
);
const text = await res.text();
console.log(text);

import requests

r = requests.get(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=10423&status=8"
)
print(r.text)

<?php
$response = file_get_contents(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=10423&status=8"
);
echo $response;

Responses

Response	Meaning
`ACCESS_CANCEL`	The rental is finished. Refunded if no code was received.
`ACCESS_READY`	The rental can’t be cancelled at this moment. Try again shortly.
`NO_ACTIVATION`	No active rental found with this ID.
`BAD_STATUS`	The status must be 6 or 8.

05

Additional SMS on a used number

Rents a number you used before again, to receive one more message — as long as we still have the number in our system. You can check availability on the Rental history page. If you request a renewal but don’t receive any message, a small penalty may be charged.

GET /stubs/handler_api.php?action=getExtraActivation

Parameters

Parameter	Type	Status	Description
`api_key`	string	Required	Your API key from the Profile page.
`action`	string	Required	Must be `getExtraActivation`.
`activationId`	number	Required	ID of the previous rental of this number.

Example request

curl "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getExtraActivation&activationId=10423"

const res = await fetch(
  "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getExtraActivation&activationId=10423"
);
const text = await res.text();
console.log(text);

import requests

r = requests.get(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getExtraActivation&activationId=10423"
)
print(r.text)

<?php
$response = file_get_contents(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getExtraActivation&activationId=10423"
);
echo $response;

Responses

Response	Meaning
`ACCESS_NUMBER:10501:14155550142`	Ready to use. New rental ID and number.
`ASLEEP:10501:14155550142:1753853008`	Number is being activated; it will be ready before the UNIX timestamp shown. Check status every 15 seconds.
`BAD_ID`	The number is no longer available, or the ID is wrong.
`NO_MONEY`	Not enough balance.

06

Services and prices

Returns every service with its current price, an availability indicator and whether it accepts multiple SMS (multi). getPricesVerification returns the same data.

GET /stubs/handler_api.php?action=getPrices

Parameters

Parameter	Type	Status	Description
`api_key`	string	Required	Your API key from the Profile page.
`action`	string	Required	`getPrices` or `getPricesVerification`.

Example request

curl "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices"

const res = await fetch(
  "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices"
);
const text = await res.text();
console.log(text);

import requests

r = requests.get(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices"
)
print(r.text)

<?php
$response = file_get_contents(
    "https://hollysms.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices"
);
echo $response;

Responses

Response	Meaning
`{"wa":{"cost":0.9,"count":512,"multi":0},…}`	JSON object keyed by service shortcode.
`BAD_KEY`	The API key is missing or wrong.

07

Webhook payload

Instead of polling, set a webhook URL on your Profile page. Every incoming SMS is then sent to your server as a POST request with a JSON body.

MethodPOST · JSON

URLhttps:// only

Reply withAny 2xx status

Payload

{
  "activationId": 10423,
  "messageId": 1,
  "service": "WhatsApp",
  "text": "Your WhatsApp code: 482-193",
  "code": "482193",
  "country": "USA:1",
  "receivedAt": "2026-10-31 12:30:57"
}

// Express.js example
app.post("/hollysms/webhook", express.json(), (req, res) => {
  const { activationId, code, text } = req.body;
  console.log(`Rental ${activationId} got code ${code}`);
  res.sendStatus(200);
});

Fields

Parameter	Type	Status	Description
`activationId`	number	Always	Rental ID, same as returned by `getNumber`.
`messageId`	number	Always	Sequence number of this SMS within the rental (1, 2, 3…).
`service`	string	Always	Service name of the rental.
`text`	string	Always	Full text of the SMS.
`code`	string	Always	The verification code found in the SMS.
`country`	string	Always	Country data of the number.
`receivedAt`	string	Always	Time the SMS arrived (`YYYY-MM-DD HH:MM:SS`, server time).

API documentation

Overview

Base URL

Rate limits

Check balance

Parameters

Example request

Responses

Get a number

Parameters

Example request

Responses

Receive the code

Parameters

Example request

Responses

Finish or cancel a rental

Parameters

Example request

Responses

Additional SMS on a used number

Parameters

Example request

Responses

Services and prices

Parameters

Example request

Responses

Webhook payload

Payload

Fields

Need help with the API?