SMS gateway API for verification codes on your own numbers

Authentication

Create a key in the dashboard under REST API. It starts with bsk_live_ and is shown once, so store it as a secret, for example BUSYSMS_API_KEY. Send it on every request, in either header:

Authorization: Bearer bsk_live_xxxxxxxx
# or
X-API-Key: bsk_live_xxxxxxxx

A key belongs to a person and only sees that person's phones, plus numbers shared with them. A key made in the dashboard can read codes, list your phones and numbers, read your account status and wake a paused phone; it cannot delete a device or manage your account, so a leaked key cannot change what you are billed. Keep keys server-side all the same: anyone holding one can read your codes.

Endpoints

Base URL https://busysms.net/api/v1. Requests are plain GETs and responses are JSON.

• GET /codes: the newest code across your numbers. With timeoutMs it waits for the next one, up to 90 seconds. Filters: service, phone, deviceId.
• GET /devices: your gateway phones with their id, name, number, platform, and online, verified and paused state, plus numbers shared with you.
• GET /numbers: just your numbers, each with canReceive and, when it cannot, a reason: unverified, verification_pending, inactive, gateway_off or phone_unreachable.
• GET /devices/:id/messages: recent captured messages for one phone, newest first. Takes service, limit (50 by default, 200 at most) and since.
• GET /account: your account with its trial and subscription status.

Wait for a code: curl, Node.js and Python

The call most integrations need is a long-poll straight after something triggers an SMS. Start the wait, trigger the sign-in, and the request returns as soon as a matching code lands.

curl -s -H "Authorization: Bearer $BUSYSMS_API_KEY" \
  "https://busysms.net/api/v1/codes?service=exampleapp&timeoutMs=60000"

const params = new URLSearchParams({ service: "exampleapp", timeoutMs: "60000" });
const res = await fetch(`https://busysms.net/api/v1/codes?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BUSYSMS_API_KEY}` },
});

if (res.status === 402) throw new Error("Trial over or subscription inactive");
if (!res.ok) throw new Error(`BusySMS ${res.status}: ${await res.text()}`);

const { code, message } = await res.json();
if (code) console.log(`${code} from ${message.sender}`);
else console.log("No new code within 60 seconds");

import os
import requests

r = requests.get(
    "https://busysms.net/api/v1/codes",
    params={"service": "exampleapp", "timeoutMs": 60000},
    headers={"Authorization": f"Bearer {os.environ['BUSYSMS_API_KEY']}"},
    timeout=75,
)
if r.status_code == 402:
    raise RuntimeError("Trial over or subscription inactive")
r.raise_for_status()

data = r.json()
if data["code"]:
    print(data["code"], "from", data["message"]["sender"])
else:
    print("No new code within 60 seconds")

Order matters less than you might fear: a code that arrived up to about a second before the request started still counts as new, and anything older does not. In tests, start the request first and trigger the SMS second; the OTP automation guide shows how in Playwright, Selenium and Cypress.

What comes back

Every /codes response has the same shape (the message object is abridged here):

{
  "code": "482913",
  "message": {
    "otpCode": "482913",
    "phone": "+447700900123",
    "sender": "ExampleApp",
    "service": "exampleapp",
    "serviceLabel": "ExampleApp",
    "bodyPreview": "Your ExampleApp verification code is 482913",
    "receivedAt": 1792674000000,
    "deviceName": "Test phone"
  }
}

code is null when nothing new arrived in time: while waiting, the API never falls back to an older code. receivedAt is in epoch milliseconds. service is a short id BusySMS gives each message: a known brand such as google, telegram or microsoft, otherwise a slug of the sender name. Pass it as service= to wait only for that sender's code.

Errors and how to handle them

• 401: the key is missing, malformed or revoked. A revoked key says so with key_revoked.
• 402 payment_required: the trial ended and there is no active subscription. Reading codes stops, but /devices still answers so you can see what is wrong, and the body carries a billingUrl.
• 403: the device belongs to another account, or the key lacks the scope for the route (insufficient_scope).
• 404: no such device.
• 409 number_unverified: that phone's number has not been verified yet, so its messages cannot be read.
• 429: rate limited. Wait retryAfterMs before retrying.

Limits and good practice

• A single wait lasts at most 90 seconds. If a code can take longer, call again with a fresh timeout instead of holding one request open.
• With several numbers, filter: phone= with the receiving number, or deviceId= for one of your phones, so a code meant for another sign-in is not returned.
• If none of your phones is capturing when a wait starts, BusySMS sends the phone a notification asking for the gateway to be switched back on. It never switches capture on remotely; a person taps.
• Captured messages are kept for up to 7 days, then deleted.
• Reading codes needs an active trial or subscription: $5 per verified number per month after a 7-day free trial. There is no per-request charge.

Beyond the REST API

The same codes are available to AI agents through the BusySMS MCP server (see SMS codes for AI agents), and to people through the Chrome extension, which fills the code into the website for you.

Numbers shared with you are included too. When a teammate shares a number's codes, /codes returns them alongside your own, and phone= picks out that number.

FAQ

Frequently asked questions