Schnellstart für die Entwickler-API

Die SmsGrab-Entwickler-API gibt deiner Software dieselben Nummern wie die App, über eine REST-API mit JSON. Sie ist ein kostenpflichtiges Produkt mit eigenen Entwicklerpreisen, wird aus deinem normalen SmsGrab-Guthaben bezahlt und hat dieselben automatischen Erstattungen.

Wer sie nutzen kann

• Ein E-Mail-Konto mit bestätigter Adresse. Gastkonten können keine Schlüssel erstellen.
• Ein Konto ohne Einschränkungen.

1. Einen API-Schlüssel erstellen

Öffne auf der Website Konto > Entwickler oder in der App Einstellungen > Entwickler-API und erstelle einen Schlüssel. Zur Sicherheit bestätigst du mit deinem Passwort und, falls aktiviert, mit deinem Code der Bestätigung in zwei Schritten. Wähle den Bereich read für reine Lesewerkzeuge oder read und purchase, um Nummern zu kaufen.

Der Schlüssel beginnt mit sgk_ und wird nur einmal angezeigt. Bewahre ihn im Geheimnisspeicher deines Servers auf. Siehe API-Schlüssel und Sicherheit.

2. Authentifizieren

Die Basis-URL ist https://smsgrab.com/api/dev/v1. Sende den Schlüssel als Bearer-Token oder im Header X-Api-Key:

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

Schlüssel gehören auf Server. Baue sie nie in eine Website, eine Browser-Erweiterung oder eine App ein, die du an andere weitergibst.

3. Guthaben und Preise prüfen

export SMSGRAB_KEY="sgk_your_key_here"

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

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Geldbeträge stehen immer in Nebeneinheiten von USD, 18 bedeutet also 0,18 USD. price_minor ist dein Entwicklerpreis, retail_price_minor der App-Preis.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. Eine Nummer kaufen

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• service und country erwarten unsere IDs, etwa whatsapp und indonesia. Bei Ländern funktionieren auch ISO-Codes wie ID.
• max_price_minor schützt dich: Ist der Preis gestiegen, wird nichts abgebucht und du erhältst 409 PRICE_CHANGED.
• Idempotency-Key macht Wiederholungen sicher. Dieselbe Anfrage mit demselben Schlüssel liefert das erste Ergebnis, statt doppelt zu kaufen.

Die Antwort ist 201 Created mit der Aktivierung:

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. Auf die SMS warten

Statt in einer engen Schleife abzufragen, lass die API die Anfrage halten, bis sich etwas ändert, bis zu 30 Sekunden:

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

Kommt eine Nachricht an, wird status zu CODE_RECEIVED und sms enthält alle bisherigen Nachrichten:

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

Lieber Push statt Abfragen? Richte Webhooks ein.

6. Abschließen oder stornieren

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

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

• finish, sobald du den Code verwendet hast. Wird nur akzeptiert, nachdem ein Code angekommen ist.
• cancel, solange du noch auf den ersten Code wartest. Der volle Preis wird erstattet.
• Tust du nichts, läuft eine Nummer ohne Code nach 20 Minuten ab und wird automatisch erstattet.

Statuswerte

Fehler

Jeder Fehler hat dieselbe Form. Reagiere auf code und reason und ignoriere Gründe, die du noch nicht kennst:

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

Häufige Fälle sind 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 mit ACTIVATION_LIMIT_REACHED (pro Konto können höchstens 100 Nummern gleichzeitig warten) und 429 RATE_LIMITED mit einem Retry-After-Header.

Die vollständige Referenz findest du in der Entwicklerdokumentation.