API Reference Overview
Base URLs, ResourceResponse envelopes, rate limit headers, and RFC 7807 Problem Details for the SMS Pro v1/v2 API.
The SMS Pro Developer API follows RESTful JSON conventions over HTTPS with an interactive OpenAPI 3.1 playground on every operation page.
API and keys
Every call uses https://api.smspro.com.
| Key prefix | Behavior |
|---|---|
sk_test_ | Simulated delivery. No wallet charge. Magic numbers select a specific outcome. |
sk_live_ | Carrier delivery. Uses wallet credit. |
Pass the key with X-Api-Key or Authorization: Bearer.
Standard Success Envelope
All JSON endpoints wrap response payloads inside a uniform ResourceResponse envelope:
{
"status": "success",
"message": "Operation completed successfully",
"data": {
"balance": 250.0,
"smsUnits": 1000,
"currency": "GHS"
}
}Rate Limit & Tracing Headers
Responses include diagnostic and rate-limiting metadata headers:
Prop
Type
RFC 7807 Problem Details Errors
Non-2xx responses return Content-Type: application/problem+json following RFC 7807:
{
"type": "https://docs.smspro.com/errors/insufficient-credits",
"title": "Insufficient Unit Credits",
"status": 422,
"detail": "Wallet PAYG balance or SMS credit units insufficient for carrier dispatch.",
"instance": "/api/v1/public/sms/send",
"code": "INSUFFICIENT_CREDITS",
"requestId": "d50c1f10-982f-4889-8d76-d392ef401032"
}| HTTP Status | Typical Causes |
|---|---|
400 Bad Request | Malformed JSON body or missing required field |
401 Unauthorized | Missing, revoked, or malformed X-Api-Key / Bearer token |
403 Forbidden | Key lacks required permission scope (for example sms:send or mfa:write) |
404 Not Found | Resource ID (messageId, batchId, otpId, or challengeId) does not exist |
422 Unprocessable Entity | Invalid E.164 recipient, >10 transactional recipients, or INSUFFICIENT_CREDITS |
429 Too Many Requests | Rate limit exceeded; inspect X-RateLimit-Reset before retrying |