API Reference

Build with SMSBulk

Modern REST API and SMS-Activate compatible endpoints. Get started in minutes.

Two API styles

Choose the format that fits your project — both backed by the same infrastructure.

Modern REST API

Clean JSON API with OpenAPI specification. Best for new integrations.

JSON request and response bodies
OpenAPI 3.0 spec at /api/docs
Bearer token or x-api-key authentication
Standard HTTP status codes

curl https://smsbulk.net/api/v1/wallet/balance \
  -H "x-api-key: YOUR_KEY"

Legacy API Compatible

Compatible with the industry-standard query-based protocol. Existing bot scripts and libraries work without code changes — just point them to our base URL.

Identical action-based protocol
Plain text response format
Compatible with existing bot libraries
Canonical country ID mapping preserved

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getBalance"

Migration guide

Quick Start

From zero to first SMS in under 5 minutes.

Get your API key

Create an API key from your dashboard. Each user can create up to 10 keys.

Open dashboard

Test authentication

Verify your key works by checking your wallet balance.

curl https://smsbulk.net/api/v1/wallet/balance \
  -H "x-api-key: YOUR_KEY"

# Response:
# { "balance": "10.00", "currency": "USD" }

Buy a number

Reserve a virtual number for SMS verification. Cost is deducted from your wallet.

curl -X POST https://smsbulk.net/api/v1/activations \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCode": "wa",
    "countryIso": "TR"
  }'

# Response:
# {
#   "id": "cuid_xxx",
#   "phoneNumber": "905551234567",
#   "status": "WAITING",
#   "userCost": "0.50"
# }

Wait for the SMS

Poll the activation endpoint until status becomes RECEIVED. The SMS code will be in the response.

curl https://smsbulk.net/api/v1/activations/cuid_xxx \
  -H "x-api-key: YOUR_KEY"

# Response (when SMS arrives):
# {
#   "id": "cuid_xxx",
#   "smsCode": "123456",
#   "status": "RECEIVED",
#   ...
# }

Authentication

Three ways to send your API key.

Pick the method that fits your environment

1. Header (recommended)

x-api-key: YOUR_API_KEY

Standard header-based authentication. Works for both REST and SMS-Activate endpoints.

2. Bearer token

Authorization: Bearer YOUR_API_KEY

Compatible with HTTP client libraries that default to the Authorization header.

3. Query string

?api_key=YOUR_API_KEY

Required for the SMS-Activate compatibility endpoint /stubs/handler_api.php.

Keep your keys secret

Never commit API keys to public repositories or expose them in client-side code. Each key has a daily quota — rotate immediately if compromised.

References

Legacy API Migration Guide

Drop-in compatibility documentation for moving existing bot integrations. Action list, country IDs, error codes.

Errors & Rate Limits

Complete error code reference, rate limit policies, retry strategies, and idempotency guidance.

Ready to ship?

Open the interactive API reference and try every endpoint live in your browser.

Open API Reference Get Started