Choose a language

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)
201 Created
{
  "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.

  1. Create an account

    Sign up with your email address and verify it. The app and the website share the same account.

  2. Create an API key

    Choose its access, restrict it to your servers and copy the secret once.

  3. Buy a number

    POST the service and the country. You get the number and its price at once.

  4. 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

Discount by 30-day spend

Volume tiers are not active right now. You pay the same prices as in the app, and approved resellers get their fixed discount.

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
Compatibility reference

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
Webhook guide
600requests per minute per key
60purchases per minute per key
100numbers waiting at once
25seconds of long polling
  • 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.

Do the app and the API share one balance?

Yes. The API uses the balance of your SmsGrab account, and every purchase and refund shows up in your wallet like any other.

More answers are in the help center

Ready to automate verification?

Create a key in your account and make your first call in minutes.