Developer API
SMS verification from your own code
One HTTPS call gives your bot or platform a real number for WhatsApp, Telegram and many more services. Read the code by webhook or long polling, and pay only for numbers that get one.
- 2,268services
- 200countries
- Autorefund when no code arrives
curl
curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
-H "Authorization: Bearer $SMSGRAB_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"service":"whatsapp","country":"indonesia"}'
Python
activation = requests.post(
"https://smsgrab.com/api/dev/v1/activations",
headers={"Authorization": f"Bearer {key}", "Idempotency-Key": str(uuid.uuid4())},
json={"service": "whatsapp", "country": "indonesia"},
timeout=30,
).json()
Node.js
const activation = await fetch('https://smsgrab.com/api/dev/v1/activations', {
method: 'POST',
headers: {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({ service: 'whatsapp', country: 'indonesia' }),
}).then((response) => response.json());
PHP
$activation = json_decode((string) $client->post('activations', [
'json' => ['service' => 'whatsapp', 'country' => 'indonesia'],
'headers' => ['Idempotency-Key' => bin2hex(random_bytes(16))],
])->getBody(), true);
Go
order := map[string]any{"service": "whatsapp", "country": "indonesia"}
err := call("POST", "/activations", order, idempotencyKey(), &activation)
{
"id": "5c1d0c2e-9f3a-4b7e-8a61-2f0c9d4e7b10",
"compat_id": 100000123,
"status": "WAITING_SMS",
"service_id": "whatsapp",
"country_id": "indonesia",
"phone_number": "+6281234567890",
"price_minor": 17,
"currency": "USD",
"expires_at": "2026-09-27T10:25:00.000Z",
"sms": []
}
Built for automation
Everything your integration needs, with the same stock, ledger and refunds as the app.
-
Clean REST API
Predictable JSON, idempotent purchases and clear error reasons you can act on.
-
Signed webhooks
HMAC-signed events for every code and status change, with retries for 24 hours.
-
Long polling
Hold a request for up to 25 seconds and get the code the moment it arrives.
-
sms-activate compatible
Point your existing tools at one new address. The actions and answers stay the same.
-
Keys you control
Read-only or buying keys, IP allowlists, daily spend caps, expiry and zero-downtime rotation.
-
Automatic refunds
No code before the number expires? The charge goes straight back to your balance.
-
Usage and request log
Daily requests, spend and errors per key, plus a searchable log of the last 7 days.
-
Volume prices
The same prices as the app, with discounts that grow automatically with your monthly volume.
Live in four steps
Your first number is only a few calls away.
-
Create an account
Sign up with your email address and verify it. The app and the website share the same account.
-
Create an API key
Choose its access, restrict it to your servers and copy the secret once.
-
Buy a number
POST the service and the country. You get the number and its price at once.
-
Receive the code
Wait with long polling or a webhook, then finish the activation.
Prices that fall as you grow
The API charges the same prices as the app. Your wholesale discount grows with your 30-day spend on every channel.
- Never more than the price of the same number in the app
- Numbers without a code are refunded automatically
- Your tier updates within minutes of reaching it
- Charged in USD from the same balance as the app
Migration
Switch from sms-activate in one line
Our compatible endpoint speaks the same protocol, so bots and panels built for sms-activate work after you change the base address and the key.
SMS-Activate closed in December 2025. Point your tools at SmsGrab and keep them running.
https://smsgrab.com/api/stubs/handler_api.php
- getNumber, getStatus, setStatus, getPrices and every other standard action
- Numeric activation ids, service codes and country ids you already use
- The same keys, limits, prices, refunds and webhooks as the REST API
curl
BASE="https://smsgrab.com/api/stubs/handler_api.php?api_key=$SMSGRAB_API_KEY"
curl -s -w '\n' "$BASE&action=getBalance"
curl -s -w '\n' "$BASE&action=getNumber&service=tg&country=6&maxPrice=0.30"
curl -s -w '\n' "$BASE&action=getStatus&id=100000123"
curl -s -w '\n' "$BASE&action=setStatus&id=100000123&status=6"
Python
import os
import time
import requests
BASE = "https://smsgrab.com/api/stubs/handler_api.php"
KEY = os.environ["SMSGRAB_API_KEY"]
def action(name: str, **params) -> str:
response = requests.get(BASE, params={"api_key": KEY, "action": name, **params}, timeout=30)
response.raise_for_status()
return response.text
print(action("getBalance"))
answer = action("getNumber", service="tg", country=6, maxPrice="0.30")
if not answer.startswith("ACCESS_NUMBER:"):
raise SystemExit(answer)
_, activation_id, number = answer.split(":")
print("Number:", number)
while True:
status = action("getStatus", id=activation_id)
if status.startswith("STATUS_OK:"):
print("Code:", status.split(":", 1)[1])
action("setStatus", id=activation_id, status=6)
break
if status == "STATUS_CANCEL":
print("Cancelled or expired, the charge was refunded")
break
time.sleep(5)
Node.js
const BASE = 'https://smsgrab.com/api/stubs/handler_api.php';
async function action(name, params = {}) {
const url = new URL(BASE);
url.search = new URLSearchParams({ api_key: process.env.SMSGRAB_API_KEY, action: name, ...params }).toString();
const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
return response.text();
}
console.log(await action('getBalance'));
const answer = await action('getNumber', { service: 'tg', country: '6', maxPrice: '0.30' });
if (!answer.startsWith('ACCESS_NUMBER:')) {
throw new Error(answer);
}
const [, id, number] = answer.split(':');
console.log('Number:', number);
for (;;) {
const status = await action('getStatus', { id });
if (status.startsWith('STATUS_OK:')) {
console.log('Code:', status.slice('STATUS_OK:'.length));
await action('setStatus', { id, status: '6' });
break;
}
if (status === 'STATUS_CANCEL') {
console.log('Cancelled or expired, the charge was refunded');
break;
}
await new Promise((resolve) => setTimeout(resolve, 5000));
}
PHP
<?php
function smsgrab(string $action, array $params = []): string
{
$query = http_build_query(['api_key' => getenv('SMSGRAB_API_KEY'), 'action' => $action] + $params);
$answer = file_get_contents('https://smsgrab.com/api/stubs/handler_api.php?'.$query, false, stream_context_create(['http' => ['timeout' => 30]]));
if ($answer === false) {
throw new RuntimeException('The request failed');
}
return $answer;
}
echo smsgrab('getBalance').PHP_EOL;
$answer = smsgrab('getNumber', ['service' => 'tg', 'country' => 6, 'maxPrice' => '0.30']);
if (! str_starts_with($answer, 'ACCESS_NUMBER:')) {
exit($answer.PHP_EOL);
}
[, $id, $number] = explode(':', $answer);
echo 'Number: '.$number.PHP_EOL;
while (true) {
$status = smsgrab('getStatus', ['id' => $id]);
if (str_starts_with($status, 'STATUS_OK:')) {
echo 'Code: '.substr($status, strlen('STATUS_OK:')).PHP_EOL;
smsgrab('setStatus', ['id' => $id, 'status' => 6]);
break;
}
if ($status === 'STATUS_CANCEL') {
echo 'Cancelled or expired, the charge was refunded'.PHP_EOL;
break;
}
sleep(5);
}
Go
package main
import (
"fmt"
"io"
"net/http"
"net/url"
"os"
"strings"
"time"
)
const base = "https://smsgrab.com/api/stubs/handler_api.php"
var client = &http.Client{Timeout: 30 * time.Second}
func action(name string, params url.Values) (string, error) {
query := url.Values{"api_key": {os.Getenv("SMSGRAB_API_KEY")}, "action": {name}}
for key, values := range params {
query[key] = values
}
response, err := client.Get(base + "?" + query.Encode())
if err != nil {
return "", err
}
defer response.Body.Close()
body, err := io.ReadAll(io.LimitReader(response.Body, 1<<20))
if err != nil {
return "", err
}
if response.StatusCode != http.StatusOK {
return "", fmt.Errorf("http %d: %s", response.StatusCode, body)
}
return string(body), nil
}
func main() {
answer, err := action("getNumber", url.Values{"service": {"tg"}, "country": {"6"}, "maxPrice": {"0.30"}})
if err != nil {
panic(err)
}
if !strings.HasPrefix(answer, "ACCESS_NUMBER:") {
fmt.Println(answer)
return
}
parts := strings.Split(answer, ":")
id := parts[1]
fmt.Println("Number:", parts[2])
for {
status, err := action("getStatus", url.Values{"id": {id}})
if err != nil {
panic(err)
}
if code, ok := strings.CutPrefix(status, "STATUS_OK:"); ok {
fmt.Println("Code:", code)
if _, err := action("setStatus", url.Values{"id": {id}, "status": {"6"}}); err != nil {
panic(err)
}
return
}
if status == "STATUS_CANCEL" {
fmt.Println("Cancelled or expired, the charge was refunded")
return
}
time.Sleep(5 * time.Second)
}
}
Real time
Codes pushed to your server
Subscribe to the events you care about and we deliver them to your HTTPS endpoint with a signature you can check.
- Number bought
- Code received
- Activation completed
- Activation cancelled
- Activation expired
- Charge refunded
- Balance running low
- Top-up created
- Top-up confirming
- Top-up credited
- Top-up expired
- Top-up under review
- Every delivery is signed with HMAC-SHA256 and a timestamp
- Only public HTTPS endpoints, checked before every delivery
- Test deliveries, a 30-day history and one-click redelivery
Developer questions
How much does the developer API cost?
There is no subscription. Each number costs the same as in the app and is paid from the same balance. Volume tiers lower that price as your 30-day spend grows, and approved resellers get a fixed discount. Numbers without a code are refunded automatically.
What happens if no code arrives?
A number stays active until the expiry time shown with it, usually 10 to 20 minutes. If no code arrives in that time, or you cancel while it is still waiting, the charge is refunded to your balance automatically.
Can I use my existing sms-activate integration?
Yes. Replace the base address with our compatible endpoint and use your SmsGrab key. The standard actions, answers and numeric ids stay the same.
What are the rate limits?
By default each key can make 600 requests and 60 purchases per minute, all keys of an account together 3,000 requests per minute, and up to 100 numbers can wait for a code at once.
How do I keep my key safe?
Keep keys on your servers only, give each app its own key, restrict it to your server addresses and set a daily spend cap. If a key may have leaked, rotate or revoke it from your account.
More answers are in the help center