{ "openapi": "3.0.3", "info": { "title": "SMSRoute API", "description": "SMSRoute is a crypto-native SMS gateway delivering to 149 countries from $0.004/SMS. No KYC at signup. Pay with BTC, ETH, USDT, LTC, XMR, or SOL.\n\n## Authentication\nAll endpoints require a Bearer token in the `Authorization` header. Get your API key from the dashboard.\n\n## Rate Limits\n- Default: 100 requests/second per API key\n- Burst: 200 requests in a 1-second window\n- Higher limits available on request\n\n## Base URL\n`https://api.sendsmsnokyc.com`", "version": "1.0.0", "contact": { "email": "support@sendsmsnokyc.com", "url": "https://www.sendsmsnokyc.com/support" }, "x-logo": { "url": "https://www.sendsmsnokyc.com/logo.svg", "altText": "SMSRoute Logo" } }, "servers": [ { "url": "https://api.sendsmsnokyc.com", "description": "Production API" } ], "tags": [ { "name": "Auth", "description": "Authentication and account registration" }, { "name": "SMS", "description": "Send SMS messages and retrieve delivery status" }, { "name": "Account", "description": "Account balance, profile, pricing, and orders" }, { "name": "HLR", "description": "Phone number validation via HLR lookup" }, { "name": "Notifications", "description": "User notifications" } ], "paths": { "/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Register new account", "description": "Create a new SMSRoute account. No KYC required — sign up with email only.", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "201": { "description": "Account created" }, "400": { "description": "Invalid input" } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Login", "description": "Authenticate and receive a session token.", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful" }, "401": { "description": "Invalid credentials" } } } }, "/sms/send": { "post": { "tags": [ "SMS" ], "summary": "Send SMS", "description": "Send a single SMS message to any mobile number worldwide. Supports alphanumeric sender IDs, scheduled delivery, and webhook delivery receipts.", "operationId": "sendSms", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "message" ], "properties": { "to": { "type": "string", "description": "Recipient phone number in E.164 format", "example": "+1234567890" }, "message": { "type": "string", "description": "SMS message content (max 1600 chars)", "maxLength": 1600 }, "from": { "type": "string", "description": "Sender ID (alphanumeric, max 11 chars)", "maxLength": 11 }, "sender_id": { "type": "string", "description": "Alternative to `from`. Sender ID." }, "callback_url": { "type": "string", "format": "uri", "description": "Webhook URL for delivery receipts" }, "marker": { "type": "string", "description": "Route marker to send via a specific gateway" } } }, "example": { "to": "+1234567890", "from": "SMSRoute", "message": "Hello from SMSRoute!", "callback_url": "https://yourapp.com/webhook" } } } }, "responses": { "200": { "description": "SMS sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "messageId": { "type": "string" }, "cost": { "type": "number", "format": "float" }, "balance": { "type": "number", "format": "float" } } }, "example": { "status": "success", "messageId": "sms_01HZX...", "cost": 0.004, "balance": 99.996 } } } }, "400": { "description": "Bad request — invalid parameters" }, "401": { "description": "Unauthorized — invalid or missing API key" }, "402": { "description": "Insufficient balance" }, "429": { "description": "Rate limit exceeded" } } } }, "/sms/send/bulk": { "post": { "tags": [ "SMS" ], "summary": "Send Bulk SMS", "description": "Send SMS messages to multiple recipients in a single request. Up to 10,000 recipients per batch. Processes in parallel on the server side.", "operationId": "sendBulkSms", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipients" ], "properties": { "recipients": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string" }, "message": { "type": "string" } } } }, "from": { "type": "string", "maxLength": 11 }, "callback_url": { "type": "string", "format": "uri" }, "marker": { "type": "string" } } }, "example": { "recipients": [ { "to": "+1234567890", "message": "Hello User 1!" }, { "to": "+0987654321", "message": "Hello User 2!" } ], "from": "SMSRoute", "callback_url": "https://yourapp.com/webhook" } } } }, "responses": { "200": { "description": "Bulk request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "batchId": { "type": "string" }, "totalMessages": { "type": "integer" }, "estimatedCost": { "type": "number" }, "status": { "type": "string" } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "429": { "description": "Rate limit exceeded" } } } }, "/sms/single/{messageId}/status": { "get": { "tags": [ "SMS" ], "summary": "Get Message Status", "description": "Retrieve delivery status of a specific message by its unique identifier.", "operationId": "getMessageStatus", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID returned from send endpoint", "example": "sms_01HZX..." } ], "responses": { "200": { "description": "Message status", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sent", "delivered", "failed", "expired", "rejected" ] }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "cost": { "type": "number" } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Message not found" } } } }, "/sms/bulk/{batchId}": { "get": { "tags": [ "SMS" ], "summary": "Get Bulk Batch Status", "description": "Retrieve status of a bulk SMS batch.", "operationId": "getBulkStatus", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch status" }, "401": { "description": "Unauthorized" }, "404": { "description": "Batch not found" } } } }, "/sms/logs": { "get": { "tags": [ "SMS" ], "summary": "Get SMS Logs", "description": "Retrieve your SMS message history with pagination and filtering.", "operationId": "getSmsLogs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "SMS logs retrieved" }, "401": { "description": "Unauthorized" } } } }, "/account/balance": { "get": { "tags": [ "Account" ], "summary": "Get Account Balance", "description": "Retrieve current account balance and usage statistics. Balance is denominated in USD.", "operationId": "getBalance", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Balance retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "number", "description": "Account balance in USD" }, "currency": { "type": "string", "enum": [ "USD" ] }, "messagesRemaining": { "type": "integer" } } }, "example": { "balance": 123.45, "currency": "USD", "messagesRemaining": 2469 } } } }, "401": { "description": "Unauthorized" } } } }, "/user/profile": { "put": { "tags": [ "Account" ], "summary": "Update Profile", "description": "Update account profile information.", "operationId": "updateProfile", "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Profile updated" }, "401": { "description": "Unauthorized" } } } }, "/user": { "get": { "tags": [ "Account" ], "summary": "Get User Info", "description": "Get authenticated user's profile information, including account status and available gateways.", "operationId": "getUser", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User info retrieved" }, "401": { "description": "Unauthorized" } } } }, "/user/dashboard/stats": { "get": { "tags": [ "Account" ], "summary": "Dashboard Stats", "description": "Get dashboard statistics including sent counts, delivery rates, and spending.", "operationId": "getDashboardStats", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Stats retrieved" }, "401": { "description": "Unauthorized" } } } }, "/prices": { "get": { "tags": [ "Account" ], "summary": "Get Pricing", "description": "Retrieve per-country SMS pricing. Returns the complete pricing grid, optionally filtered by country code.", "operationId": "getPricing", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country code to filter by", "example": "US" } ], "responses": { "200": { "description": "Pricing retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" }, "currency": { "type": "string", "enum": [ "USD" ] } } } } } } } } }, "401": { "description": "Unauthorized" } } } }, "/user/transactions": { "get": { "tags": [ "Account" ], "summary": "Get Transactions", "description": "Retrieve transaction history including top-ups, SMS costs, and refunds.", "operationId": "getTransactions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Transactions retrieved" }, "401": { "description": "Unauthorized" } } } }, "/orders": { "get": { "tags": [ "Account" ], "summary": "Get Orders", "description": "Retrieve order/payment history.", "operationId": "getOrders", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Orders retrieved" }, "401": { "description": "Unauthorized" } } } }, "/user/country/routes": { "get": { "tags": [ "SMS" ], "summary": "Get Country Routes", "description": "Get the routing configuration for the authenticated user per country.", "operationId": "getCountryRoutes", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Routes retrieved" }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "SMS" ], "summary": "Set Country Routes", "description": "Set specific carrier route preferences per country.", "operationId": "setCountryRoutes", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Routes updated" }, "401": { "description": "Unauthorized" } } }, "delete": { "tags": [ "SMS" ], "summary": "Reset Country Routes", "description": "Reset country routing to defaults.", "operationId": "resetCountryRoutes", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Routes reset" } } } }, "/hlr/lookup": { "post": { "tags": [ "HLR" ], "summary": "HLR Lookup", "description": "Perform a Home Location Register lookup to validate a phone number, identify the carrier, and determine if the number is active. Use before sending SMS to reduce costs from undeliverable messages.", "operationId": "hlrLookup", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "Phone number in E.164 format" } } }, "example": { "phone": "+1234567890" } } } }, "responses": { "200": { "description": "HLR lookup completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "valid": { "type": "boolean" }, "carrier": { "type": "string" }, "country": { "type": "string" }, "type": { "type": "string", "enum": [ "mobile", "landline", "voip", "unknown" ] }, "ported": { "type": "boolean" } } }, "example": { "phone": "+1234567890", "valid": true, "carrier": "Verizon Wireless", "country": "US", "type": "mobile", "ported": false } } } }, "400": { "description": "Invalid phone number" }, "401": { "description": "Unauthorized" } } } }, "/hlr/lookup/bulk": { "post": { "tags": [ "HLR" ], "summary": "Bulk HLR Lookup", "description": "Perform HLR lookups on multiple phone numbers in a single request. Max 10,000 numbers per batch.", "operationId": "hlrLookupBulk", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone_numbers" ], "properties": { "phone_numbers": { "type": "array", "maxItems": 10000, "items": { "type": "string" } } } }, "example": { "phone_numbers": [ "+1234567890", "+0987654321" ] } } } }, "responses": { "200": { "description": "Bulk lookup completed" }, "400": { "description": "Invalid input" }, "401": { "description": "Unauthorized" } } } }, "/hlr/history": { "get": { "tags": [ "HLR" ], "summary": "HLR History", "description": "Retrieve history of previous HLR lookups.", "operationId": "hlrHistory", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "HLR history retrieved" }, "401": { "description": "Unauthorized" } } } }, "/user/notifications": { "get": { "tags": [ "Notifications" ], "summary": "Get Notifications", "description": "Retrieve user notifications.", "operationId": "getNotifications", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Notifications retrieved" }, "401": { "description": "Unauthorized" } } } }, "/health": { "get": { "tags": [ "Account" ], "summary": "Health Check", "description": "Simple health check endpoint.", "operationId": "healthCheck", "responses": { "200": { "description": "Service is healthy" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key obtained from the SMSRoute dashboard. Pass as `Authorization: Bearer YOUR_API_KEY`." } }, "schemas": { "Error": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "retry_after": { "type": "integer", "description": "Seconds until rate limit resets (only on 429)" } } } } }, "x-webhooks": { "deliveryReceipt": { "post": { "summary": "Delivery Receipt Webhook", "description": "When you provide a `callback_url` in the send request, SMSRoute will POST delivery status updates to that URL. Expect a JSON body with the message ID, status, and delivery timestamp.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" }, "status": { "type": "string", "enum": [ "delivered", "failed", "expired", "rejected" ] }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "to": { "type": "string" }, "cost": { "type": "number" } } } } } }, "responses": { "200": { "description": "Acknowledge receipt with 200 OK" } } } } } }