API Documentation

Build with SMS Connect

Our REST API makes it easy to integrate SMS into your application. All endpoints are versioned and secured with API keys.

Get Started Send SMS Sign Up Free

Authentication

All API requests require API Key + Secret authentication

Authentication Flow

  1. Create an account — Register via /api/v1/register or sign up on the website
  2. Log in — Use /api/v1/login to get your API credentials
  3. Generate API Keys — Manage keys from Dashboard → API Keys
  4. Authenticate requests — Send both Authorization and X-API-SECRET headers

Required Headers for Protected Endpoints

Authorization: Bearer sms_abc123def456 // Your API Key X-API-SECRET: your_secret_key_here // Your API Secret Content-Type: application/json Accept: application/json
Important

Both headers are required for every protected endpoint. If either is missing or invalid, you will receive a 401 Unauthorized response.

Branding

Every SMS automatically includes the brand link https://smsconnect.tech at the end of the message. This helps promote your brand and complies with our terms of service.

POST /api/v1/register Public

Register a new user account

ParameterTypeRequiredDescription
first_namestringYesUser's first name
last_namestringYesUser's last name
emailstringYesValid email address (unique)
passwordstringYesMinimum 8 characters
password_confirmationstringYesMust match password
phonestringNoPhone number (optional)
// Request body { "first_name": "John", "last_name": "Doe", "email": "john@example.com", "password": "password123", "password_confirmation": "password123", "phone": "250788123456" } // 201 Response { "success": true, "message": "User registered successfully", "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "250788123456" } } }
POST /api/v1/login Public

Login and get your API credentials

ParameterTypeRequiredDescription
emailstringYesRegistered email address
passwordstringYesAccount password
// Request body { "email": "john@example.com", "password": "password123" } // 200 Response { "success": true, "message": "Login successful", "data": { "user": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "250788123456" }, "api_key": "sms_xxxxxxxxxxxxxxxxx", "api_secret": "your_secret_key_here", "wallet_balance": 5000 } }
Security Note

Your api_secret is only returned once. Store it securely. If you lose it, regenerate a new key from the Dashboard.

POST /api/v1/logout Auth Required

Logout and invalidate token

// Required headers Authorization: Bearer your_api_key X-API-SECRET: your_secret_key // 200 Response { "success": true, "message": "Logged out successfully" }
GET /api/v1/user Auth Required

Get authenticated user details

// Required headers Authorization: Bearer your_api_key X-API-SECRET: your_secret_key // 200 Response { "success": true, "data": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "250788123456", "role": "user", "wallet": { "balance": 5000, "currency": "RWF" } } }

Base URL

All API endpoints are relative to the base URL below

Base URL:  https://smsconnect.tech/api/v1
Documentation

Full API documentation available at: https://smsconnect.tech/docs

Brand URL: https://smsconnect.tech

Rate Limits

API request limits based on your plan

Free Plan
100
requests / minute
Business Plan
1,000
requests / minute
Enterprise Plan
10,000
requests / minute — custom limits available

Rate limits are enforced per API key. Check your plan limits in the dashboard.

Error Handling

All errors return a JSON body with a consistent shape

// Error response shape { "success": false, "message": "Insufficient balance", "errors": null, "documentation": "https://smsconnect.tech/docs", "support_url": "https://smsconnect.tech/support" }
400 Bad Request — Validation failed
401 Unauthorized — Invalid API credentials
403 Forbidden — Permission denied
404 Not Found — Resource not found
422 Unprocessable Entity — Validation errors
429 Too Many Requests — Rate limit exceeded
500 Internal Server Error — Something went wrong

SMS Endpoints

Send and manage SMS messages with automatic branding

POST /api/v1/sms/send Auth Required

Send a single SMS to one recipient. Cost: 10 RWF per SMS. Automatically includes brand link.

ParameterTypeRequiredDescription
recipientstringYesPhone number — format: 2507XXXXXXXX or 07XXXXXXXX
messagestringYesSMS content (max 160 characters). Brand link auto-appended.
sender_idstringNoCustom sender ID (max 11 characters)
schedule_atdatetimeNoSchedule delivery — format: Y-m-d H:i:s
recipient_typestringNocontact · group · manual (default: contact)
Wallet Requirement

Every SMS costs 10 RWF and deducts funds from your wallet. If your balance is insufficient, the request will fail with 400 Insufficient balance.

Branding

Each message automatically includes "\n\nPowered by SMSConnect: https://smsconnect.tech" at the end. The system ensures the total message stays within 160 characters.

// Headers Authorization: Bearer sms_abc123def456 X-API-SECRET: your_secret_key_here Content-Type: application/json // Request body { "recipient": "250788123456", "message": "Your order has been confirmed!", "sender_id": "MYCOMPANY" } // 200 Response with branded message // Actual message sent: "Your order has been confirmed!\n\nPowered by SMSConnect: https://smsconnect.tech" { "success": true, "message": "SMS sent successfully. Full API docs: https://smsconnect.tech/docs", "data": { "message_id": 123, "status": "sent", "cost": 10, "balance": 4990, "brand": "https://smsconnect.tech", "documentation": "https://smsconnect.tech/docs" } }
POST /api/v1/sms/bulk Auth Required

Send SMS to multiple recipients at once. Cost: 10 RWF per SMS. Max 1000 recipients per request.

ParameterTypeRequiredDescription
recipientsarrayYesArray of phone numbers (max 1000)
recipients.*stringYesPhone number — format: 2507XXXXXXXX
messagestringYesSMS content (max 160 characters)
sender_idstringNoCustom sender ID (max 11 characters)
schedule_atdatetimeNoSchedule delivery — format: Y-m-d H:i:s
recipient_typestringNocontact · group · manual
{ "recipients": [ "250788123456", "250788654321", "250788999888" ], "message": "Promotional message from our company!", "sender_id": "MYCOMPANY" } // 200 Response { "success": true, "message": "Bulk SMS sent successfully. Full API docs: https://smsconnect.tech/docs", "data": { "total": 3, "sent": 3, "failed": 0, "cost": 30, "balance": 4960, "batch_id": "BATCH20240115ABC123", "brand": "https://smsconnect.tech", "documentation": "https://smsconnect.tech/docs" } }
POST /api/v1/sms/schedule Auth Required

Schedule an SMS for future delivery. Funds are reserved until delivery.

ParameterTypeRequiredDescription
recipientstringYesPhone number — format: 2507XXXXXXXX
messagestringYesSMS content (max 160 characters)
scheduled_atdatetimeYesSchedule delivery — format: Y-m-d H:i:s (must be in future)
sender_idstringNoCustom sender ID (max 11 characters)
recipient_typestringNocontact · group · manual
{ "recipient": "250788123456", "message": "Reminder: Meeting tomorrow at 10 AM", "scheduled_at": "2026-07-09 09:00:00", "sender_id": "MYCOMPANY" } // 200 Response { "success": true, "message": "SMS scheduled successfully. Full API docs: https://smsconnect.tech/docs", "data": { "message_id": 124, "status": "pending", "scheduled_at": "2026-07-09 09:00:00", "cost": 10, "balance": 4980, "brand": "https://smsconnect.tech", "documentation": "https://smsconnect.tech/docs" } }
GET /api/v1/sms/history Auth Required

Get SMS history with optional filters — only your messages are returned

ParameterTypeRequiredDescription
statusstringNopending · sending · sent · delivered · failed
start_datedateNoFilter from date — format: Y-m-d
end_datedateNoFilter to date — format: Y-m-d
recipient_typestringNocontact · group · manual
pageintegerNoPage number (default: 1)
per_pageintegerNoItems per page (default: 20, max: 100)
// Query parameters ?status=sent&per_page=10 // 200 Response { "success": true, "message": "SMS history retrieved successfully. Full API docs: https://smsconnect.tech/docs", "data": { "current_page": 1, "data": [ { "id": 123, "recipient": "250788123456", "message": "Your order has been confirmed!\n\nPowered by SMSConnect: https://smsconnect.tech", "original_message": "Your order has been confirmed!", "status": "sent", "cost": 10, "has_branding": true, "created_at": "2024-01-15T14:30:00.000000Z" } ], "total": 50, "brand": "https://smsconnect.tech", "documentation": "https://smsconnect.tech/docs" } }
GET /api/v1/sms/{id}/status Auth Required

Check the delivery status of a specific SMS — only your messages

// 200 Response { "success": true, "message": "SMS status retrieved successfully. Full API docs: https://smsconnect.tech/docs", "data": { "id": 123, "recipient": "250788123456", "message": "Your order has been confirmed!\n\nPowered by SMSConnect: https://smsconnect.tech", "original_message": "Your order has been confirmed!", "status": "delivered", "cost": 10, "has_branding": true, "created_at": "2024-01-15T14:30:00.000000Z", "delivered_at": "2024-01-15T14:30:05.000000Z", "brand": "https://smsconnect.tech", "documentation": "https://smsconnect.tech/docs" } }
GET /api/v1/sms/statistics Auth Required

Get aggregated SMS statistics for your account

// 200 Response { "success": true, "message": "SMS statistics retrieved successfully. Full API docs: https://smsconnect.tech/docs", "data": { "total": 150, "sent": 10, "delivered": 135, "failed": 5, "pending": 0, "sending": 0, "total_cost": 1500, "cost_per_sms": 10, "last_30_days": 45, "by_recipient_type": { "contact": 120, "group": 25, "manual": 5 }, "brand": "https://smsconnect.tech", "documentation": "https://smsconnect.tech/docs" } }
GET /api/v1/sms/cost Auth Required

Get the current cost per SMS

// 200 Response { "success": true, "data": { "cost_per_sms": 10, "currency": "RWF", "brand": "https://smsconnect.tech", "documentation": "https://smsconnect.tech/docs" } }

Ready to integrate?

Get your API key and start building today — free to sign up. Only 10 RWF per SMS with automatic branding.

Get API Key Dashboard Back to Home