API Reference & Guides
Authenticate with bearer API keys, send SMS, place calls, manage SIP settings, and fetch call logs.
Authentication
Use bearer API keys created in the dashboard. Send keys via the Authorization header.
Authorization: Bearer sk_live_yourkey
- Rotate keys regularly; revoke compromised keys immediately.
- Support optional IP allowlists and per-key scoping (staging/production).
Base URL
Production: https://api.sms-voip.local/api/v1
Sandbox: https://sandbox.sms-voip.local/api/v1
Ping: GET /api/v1/ping
SMS: Send
Send a single SMS. For bulk, loop or batch client-side.
Responses include message_id, status, and cost. Delivery reports POST to your callback_url.
VoIP: SIP management
POST /api/v1/voip/caller-id POST /api/v1/voip/password POST /api/v1/voip/topup GET /api/v1/voip/logs
Use these endpoints to update caller ID and SIP password, move funds from app wallet to SIP, and read call logs.
# Update caller ID
curl -X POST https://api.sms-voip.local/api/v1/voip/caller-id \
-H "Authorization: Bearer sk_live_yourkey" \
-H "Content-Type: application/json" \
-d '{ "caller_id": "+15550111222" }'
# Update SIP password
curl -X POST https://api.sms-voip.local/api/v1/voip/password \
-H "Authorization: Bearer sk_live_yourkey" \
-H "Content-Type: application/json" \
-d '{ "sip_password": "NewStrongPassword123" }'
# Top up SIP wallet
curl -X POST https://api.sms-voip.local/api/v1/voip/topup \
-H "Authorization: Bearer sk_live_yourkey" \
-H "Content-Type: application/json" \
-d '{ "amount": 25 }'
# SIP call logs
curl -X GET "https://api.sms-voip.local/api/v1/voip/logs?limit=10&offset=0&search=+1555" \
-H "Authorization: Bearer sk_live_yourkey"
Voice: Set caller ID / place call
Rings, answer, duration, recording URL (when enabled) via webhooks.
Rates
GET /api/v1/rates Authorization: Bearer sk_live_yourkey (optional for public rates)
Returns country, ISO code, SMS, voice, currency, and route label.
Status
GET /api/v1/status
Returns overall status, notice, and component list.
Try it (mocked)
Simulated responses without sending traffic.
Webhooks
We sign webhook requests with an HMAC header X-Signature. Verify using your webhook secret.
POST https://example.com/webhooks/dlr
Headers:
X-Signature: t=1728000000,v1=abc123...
{
"event": "delivery_report",
"message_id": "msg_123",
"status": "delivered",
"delivered_at": "2026-01-12T20:15:00Z",
"cost": 0.006
}
Errors
400: validation error (missing/invalid parameters).401: invalid or missing API key.403: blocked, suspended, or IP not allowed.429: rate limit exceeded.5xx: transient service issue; retry with backoff.
SDK examples
# PHP (Guzzle)
$client = new \\GuzzleHttp\\Client(['base_uri' => 'https://api.sms-voip.local']);
$resp = $client->post('/api/v1/sms/send', [
'headers' => ['Authorization' => 'Bearer sk_live_key'],
'json' => ['to' => '+15551234567', 'text' => 'Hi!']
]);
# Node (fetch)
await fetch('https://api.sms-voip.local/api/v1/voice/call', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
to: '+15559876543',
from: '+15550111222',
caller_id: '+15550111222'
})
});
Rate limits
- Default: 120 requests/min per API key.
- Burst traffic for OTP can be requested via support.
- Use idempotency keys for retries to avoid duplicates.
Idempotency
Idempotency-Key: msg-123-otp
Support & Sandbox
Use sandbox credentials for non-billable testing. For production enablement, ensure KYC, sender IDs, and webhook verification are configured.