Snelstart voor de ontwikkelaars-API

De ontwikkelaars-API van SmsGrab geeft je software dezelfde nummers als de app, via een REST-API die JSON spreekt. Het is een betaald product met eigen ontwikkelaarsprijzen, betaald met je gewone SmsGrab-saldo en gedekt door dezelfde automatische terugbetalingen.

Wie het kan gebruiken

• Een e-mailaccount met een bevestigd adres. Gastaccounts kunnen geen sleutels maken.
• Een account zonder beperkingen.

1. Maak een API-sleutel

Open Account > Ontwikkelaars op de website, of Instellingen > Ontwikkelaars-API in de app, en maak een sleutel. Voor de veiligheid bevestig je met je wachtwoord, en met je code voor verificatie in twee stappen als die aanstaat. Kies de scope read voor tools die alleen lezen, of read en purchase om nummers te kopen.

De sleutel begint met sgk_ en wordt maar één keer getoond. Bewaar hem in de geheime opslag van je server. Zie API-sleutels en beveiliging.

2. Authenticeren

De basis-URL is https://smsgrab.com/api/dev/v1. Stuur de sleutel als bearer-token, of in de header X-Api-Key:

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

Sleutels horen op servers. Zet ze nooit in een website, een browserextensie of een app die je aan anderen geeft.

3. Bekijk je saldo en de prijzen

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"

Bedragen staan altijd in kleinste eenheden van USD, dus 18 betekent 0,18 USD. price_minor is je ontwikkelaarsprijs en retail_price_minor de prijs in de app.

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

4. Koop een nummer

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 en country nemen onze id's, zoals whatsapp en indonesia. Landen accepteren ook ISO-codes zoals ID.
• max_price_minor beschermt je: is de prijs gestegen, dan wordt er niets afgeschreven en krijg je 409 PRICE_CHANGED.
• Idempotency-Key maakt opnieuw proberen veilig. Herhaal je het verzoek met dezelfde sleutel, dan krijg je het eerste resultaat terug in plaats van twee keer te kopen.

Het antwoord is 201 Created met de activering:

{ "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. Wacht op de sms

Laat de API het verzoek tot 30 seconden openhouden tot er iets verandert, in plaats van in een strakke lus te pollen:

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

Komt er een bericht binnen, dan wordt status CODE_RECEIVED en bevat sms alle berichten tot nu toe:

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

Liever push dan pollen? Stel webhooks in.

6. Afronden of annuleren

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 zodra je de code hebt gebruikt. Dit wordt pas geaccepteerd nadat er een code is binnengekomen.
• cancel zolang je nog op de eerste code wacht. De volledige prijs wordt terugbetaald.
• Doe je niets, dan verloopt een nummer zonder code na 20 minuten en wordt het automatisch terugbetaald.

Statuswaarden

Fouten

Elke fout heeft dezelfde vorm. Reageer op code en reason, en negeer redenen die je nog niet kent:

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

Veelvoorkomende gevallen zijn 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 met ACTIVATION_LIMIT_REACHED (per account kunnen maximaal 100 nummers tegelijk wachten) en 429 RATE_LIMITED met een header Retry-After.

De volledige referentie staat in de ontwikkelaarsdocumentatie.