Developer API reference

PHP

<?php

function verifySmsGrabSignature(string $header, string $body, string $secret): bool
{
    $parts = [];
    foreach (explode(',', $header) as $part) {
        [$name, $value] = array_pad(explode('=', $part, 2), 2, '');
        $parts[trim($name)] = trim($value);
    }
    $timestamp = (int) ($parts['t'] ?? 0);
    $expected = hash_hmac('sha256', $timestamp.'.'.$body, $secret);

    return abs(time() - $timestamp) <= 300 && hash_equals($expected, $parts['v1'] ?? '');
}

$body = file_get_contents('php://input');
if (! verifySmsGrabSignature($_SERVER['HTTP_SMSGRAB_SIGNATURE'] ?? '', $body, getenv('SMSGRAB_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
http_response_code(200);

Python

import hashlib
import hmac
import time


def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    timestamp = int(parts.get("t", "0"))
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return abs(time.time() - timestamp) <= 300 and hmac.compare_digest(expected, parts.get("v1", ""))

Node.js

import crypto from 'node:crypto';

export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.split('=', 2)));
  const timestamp = Number(parts.t ?? 0);
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'utf8');
  return Math.abs(Date.now() / 1000 - timestamp) <= 300
    && given.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(expected, 'utf8'), given);
}

Go

package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

func Verify(header string, body []byte, secret string) bool {
	var timestamp int64
	var signature string
	for _, part := range strings.Split(header, ",") {
		name, value, found := strings.Cut(strings.TrimSpace(part), "=")
		if !found {
			continue
		}
		switch name {
		case "t":
			timestamp, _ = strconv.ParseInt(value, 10, 64)
		case "v1":
			signature = value
		}
	}
	age := time.Now().Unix() - timestamp
	if age > 300 || age < -300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(strconv.FormatInt(timestamp, 10) + "."))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(signature))
}

curl

BASE="https://smsgrab.com/api/stubs/handler_api.php?api_key=$SMSGRAB_API_KEY"

curl -s "$BASE&action=getBalance"
curl -s "$BASE&action=getNumber&service=tg&country=6"
curl -s "$BASE&action=getStatus&id=100000123"
curl -s "$BASE&action=setStatus&id=100000123&status=6"

Python

import os

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)
if answer.startswith("ACCESS_NUMBER:"):
    _, activation_id, number = answer.split(":")
    print(activation_id, number)

curl

export SMSGRAB_API_KEY="sgk_your_key"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_API_KEY"

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":"telegram","country":"indonesia","max_price_minor":30}'

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_API_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_API_KEY"

Python

import os
import uuid

import requests

API = "https://smsgrab.com/api/dev/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SMSGRAB_API_KEY']}"


def buy(service: str, country: str, max_price_minor: int) -> dict:
    response = session.post(
        f"{API}/activations",
        json={"service": service, "country": country, "max_price_minor": max_price_minor},
        headers={"Idempotency-Key": str(uuid.uuid4())},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()


def wait_for_code(activation_id: str) -> str | None:
    while True:
        response = session.get(f"{API}/activations/{activation_id}", params={"wait": 25}, timeout=40)
        response.raise_for_status()
        activation = response.json()
        if activation["sms"]:
            return activation["sms"][-1]["code"]
        if activation["status"] != "WAITING_SMS":
            return None


activation = buy("telegram", "indonesia", 30)
print("Number:", activation["phone_number"])
code = wait_for_code(activation["id"])
if code:
    print("Code:", code)
    session.post(f"{API}/activations/{activation['id']}/finish", timeout=30).raise_for_status()
else:
    print("No code arrived, the charge was refunded")

Node.js

import { randomUUID } from 'node:crypto';

const API = 'https://smsgrab.com/api/dev/v1';

async function call(path, { method = 'GET', body, idempotencyKey } = {}) {
  const response = await fetch(`${API}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.SMSGRAB_API_KEY}`,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = response.status === 204 ? null : await response.json();
  if (!response.ok) {
    throw new Error(`${data?.code ?? response.status}: ${data?.message ?? ''}`);
  }
  return data;
}

let activation = await call('/activations', {
  method: 'POST',
  body: { service: 'telegram', country: 'indonesia', max_price_minor: 30 },
  idempotencyKey: randomUUID(),
});
console.log('Number:', activation.phone_number);

while (activation.sms.length === 0 && activation.status === 'WAITING_SMS') {
  activation = await call(`/activations/${activation.id}?wait=25`);
}

if (activation.sms.length > 0) {
  console.log('Code:', activation.sms.at(-1).code);
  await call(`/activations/${activation.id}/finish`, { method: 'POST' });
} else {
  console.log('No code arrived, the charge was refunded');
}

PHP

<?php

require __DIR__.'/vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://smsgrab.com/api/dev/v1/',
    'headers' => ['Authorization' => 'Bearer '.getenv('SMSGRAB_API_KEY')],
    'timeout' => 40,
]);

$read = static fn ($response): array => json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);

$activation = $read($client->post('activations', [
    'json' => ['service' => 'telegram', 'country' => 'indonesia', 'max_price_minor' => 30],
    'headers' => ['Idempotency-Key' => bin2hex(random_bytes(16))],
]));
echo 'Number: '.$activation['phone_number'].PHP_EOL;

while ($activation['sms'] === [] && $activation['status'] === 'WAITING_SMS') {
    $activation = $read($client->get('activations/'.$activation['id'], ['query' => ['wait' => 25]]));
}

if ($activation['sms'] !== []) {
    echo 'Code: '.$activation['sms'][array_key_last($activation['sms'])]['code'].PHP_EOL;
    $client->post('activations/'.$activation['id'].'/finish');
} else {
    echo 'No code arrived, the charge was refunded'.PHP_EOL;
}

Go

package main

import (
	"bytes"
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

const api = "https://smsgrab.com/api/dev/v1"

type Activation struct {
	ID          string `json:"id"`
	Status      string `json:"status"`
	PhoneNumber string `json:"phone_number"`
	SMS         []struct {
		Code string `json:"code"`
	} `json:"sms"`
}

var client = &http.Client{Timeout: 40 * time.Second}

func call(method, path string, body any, idempotencyKey string, out any) error {
	var payload bytes.Buffer
	if body != nil {
		if err := json.NewEncoder(&payload).Encode(body); err != nil {
			return err
		}
	}
	request, err := http.NewRequest(method, api+path, &payload)
	if err != nil {
		return err
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("SMSGRAB_API_KEY"))
	if body != nil {
		request.Header.Set("Content-Type", "application/json")
	}
	if idempotencyKey != "" {
		request.Header.Set("Idempotency-Key", idempotencyKey)
	}
	response, err := client.Do(request)
	if err != nil {
		return err
	}
	defer response.Body.Close()
	if response.StatusCode >= 300 {
		var failure struct {
			Code    string `json:"code"`
			Message string `json:"message"`
		}
		_ = json.NewDecoder(response.Body).Decode(&failure)
		return fmt.Errorf("%s: %s", failure.Code, failure.Message)
	}
	if out == nil {
		return nil
	}
	return json.NewDecoder(response.Body).Decode(out)
}

func idempotencyKey() string {
	buffer := make([]byte, 16)
	_, _ = rand.Read(buffer)
	return hex.EncodeToString(buffer)
}

func main() {
	var activation Activation
	order := map[string]any{"service": "telegram", "country": "indonesia", "max_price_minor": 30}
	if err := call("POST", "/activations", order, idempotencyKey(), &activation); err != nil {
		panic(err)
	}
	fmt.Println("Number:", activation.PhoneNumber)
	for len(activation.SMS) == 0 && activation.Status == "WAITING_SMS" {
		if err := call("GET", "/activations/"+activation.ID+"?wait=25", nil, "", &activation); err != nil {
			panic(err)
		}
	}
	if len(activation.SMS) == 0 {
		fmt.Println("No code arrived, the charge was refunded")
		return
	}
	fmt.Println("Code:", activation.SMS[len(activation.SMS)-1].Code)
	if err := call("POST", "/activations/"+activation.ID+"/finish", nil, "", nil); err != nil {
		panic(err)
	}
}