Receive SMS API: get verification codes on numbers you own

BusySMS compared with virtual-number services

When to use which

If you need a throwaway number for a one-off test and nothing will ever depend on it, a virtual number is the faster route, and BusySMS is the wrong tool. If the account matters, such as your company's admin login, a test account your CI signs in to every night, or the number your customers already know, receive on a number you own.

BusySMS is also not a way around anyone's verification. It reads codes sent to numbers you control, for accounts that are yours. It cannot read anybody else's messages, and it is not built for creating accounts in bulk.

How receiving works with BusySMS

1. 1

   Put the receiver on the phone

   On Android, the BusySMS app from Google Play. On an iPhone, a Shortcuts automation, with or without the BusySMS iPhone app.

2. 2

   Verify the number

   BusySMS texts a code to the number and the phone passes it back. That proves the SIM holds the number; until then nothing is stored or billed.

3. 3

   Receive

   Only texts that look like verification codes are kept. Each one is tagged with the receiving number, the sender, a detected service and the time it arrived.

4. 4

   Read

   Your program calls the REST API, an AI agent uses MCP, and a person sees the code in the dashboard or lets the Chrome extension type it in.

Which numbers you can receive on

• Any number on a SIM in a phone you own: an Android phone on Android 8.0 or later with the BusySMS app, or an iPhone on iOS 14 or later through Shortcuts.
• Each SIM in a dual-SIM phone is a separate number, verified and billed on its own.
• Numbers are verified with an SMS round-trip, so you cannot add a number whose SIM you do not hold.

Receive a code through the API

Create a key in the dashboard under REST API and keep it in an environment variable. Then wait for the next code on one specific number:

# Digits only: the receiving number +44 7700 900123
curl -s -H "Authorization: Bearer $BUSYSMS_API_KEY" \
  "https://busysms.net/api/v1/codes?phone=447700900123&timeoutMs=60000"

const params = new URLSearchParams({ phone: "447700900123", timeoutMs: "60000" });
const res = await fetch(`https://busysms.net/api/v1/codes?${params}`, {
  headers: { Authorization: `Bearer ${process.env.BUSYSMS_API_KEY}` },
});
if (!res.ok) throw new Error(`BusySMS ${res.status}`);

const { code } = await res.json(); // null if nothing new arrived
console.log(code);

import os
import requests

r = requests.get(
    "https://busysms.net/api/v1/codes",
    params={"phone": "447700900123", "timeoutMs": 60000},
    headers={"Authorization": f"Bearer {os.environ['BUSYSMS_API_KEY']}"},
    timeout=75,
)
r.raise_for_status()
print(r.json()["code"])  # None if nothing new arrived

phone matches the receiving number (digits are enough), so with several numbers on the account you get the code for the right one. The wait lasts up to 90 seconds and returns null rather than an older code if nothing new arrives.

To read history instead of waiting, list one phone's recent messages with GET /api/v1/devices/:id/messages; captured messages are kept for up to 7 days. Every endpoint and error is in the SMS gateway API guide.

What is received, and what is not

• You choose at setup, for each Android SIM: every text, or verification-style texts only. Only you can see the other texts.
• On an iPhone the check happens on the phone itself: a text that does not look like a code never leaves it.
• Nothing is captured while the gateway is off.
• A number has to pass verification before anything it receives is stored.

FAQ

Frequently asked questions