SMS API Documentation

Integrate SMS capabilities into your applications with our RESTful API. Send single or bulk messages, check delivery status, and manage your account programmatically.

Version 2.0.1 REST API HTTPS Secure JSON Responses
Your API Key
Please login to view your API key
Keep this secret! Do not share with anyone.
Quick Navigation
Quick Links
cURL Examples PowerShell Python

Introduction

The RAYPROTECH System SMS API allows you to send SMS messages programmatically through your applications. Our API is RESTful, uses JSON for requests and responses, and supports both single and bulk messaging.

Pro Tip: All API requests must use HTTPS and include your API key in the request body.

Authentication

All API endpoints require authentication using your API key. Include the API key in the request body as shown below:

{
    "api_key": "your_api_key_here"
}

Your API key is unique to your account and should be kept confidential. You can find your API key in your dashboard or in the API Key section above.

Base URL

All API requests should be made to the following base URL:

https://texin.hotspotbillingsystem.co.ke/api/

For example, to get your balance, you would send a POST request to:

https://texin.hotspotbillingsystem.co.ke/api/get_balance

All Endpoints

GET
/api/

Get API information and available endpoints

View Details
POST
/api/send_sms

Send a single SMS message

View Details
POST
/api/send_bulk_sms

Send SMS messages to multiple recipients

View Details
POST
/api/check_status

Check the status of a sent message

View Details
POST
/api/get_balance

Get your account balance and information

View Details
GET
/api/test_connection

Test API connectivity

View Details

Send SMS

Send a single SMS message to a recipient.

POST /api/send_sms
Request Parameters
Parameter Type Required Description
api_key String Yes Your API authentication key
recipient String Yes Recipient phone number (format: 2547XXXXXXXX or 07XXXXXXXX)
message String Yes SMS message content (max 160 characters per SMS)
sender_id String Optional Sender ID (defaults to "Texin")
Request Example
{
    "api_key": "your_api_key_here",
    "recipient": "254759924977",
    "message": "Hello from RAYPROTECH System API!",
    "sender_id": "Texin"
}
Response Example (Success)
{
    "success": true,
    "message": "SMS sent successfully!",
    "message_id": "API-1768205981",
    "recipient": "254759924977",
    "sender_id": "Texin",
    "units_used": 1,
    "message_length": 37,
    "cost": 0.3,
    "new_balance": 92,
    "simulation_mode": false,
    "details": {
        "To": "254759924977",
        "Message ID": "API-1768205981",
        "Units used": 1,
        "Cost": "KES 0.30",
        "New balance": "92 credits",
        "Length": "37 characters"
    }
}
Response Example (Error)
{
    "success": false,
    "message": "Failed to send SMS",
    "error": "API Error: Given SenderId is invalid. Please use valid SenderId.",
    "sender_id_used": "TEXIN"
}

Bulk SMS

Send SMS messages to multiple recipients at once.

POST /api/send_bulk_sms
Request Parameters
Parameter Type Required Description
api_key String Yes Your API authentication key
recipients Array Yes Array of recipient phone numbers
message String Yes SMS message content
sender_id String Optional Sender ID (defaults to "Texin")
Request Example
{
    "api_key": "your_api_key_here",
    "recipients": [
        "254759924977",
        "254725095094",
        "254700000001"
    ],
    "message": "Special offer just for you!",
    "sender_id": "Texin"
}
Response Example (Success)
{
    "success": true,
    "message": "Bulk SMS sent: 3 successful, 0 failed",
    "statistics": {
        "total_attempted": 3,
        "successful": 3,
        "failed": 0,
        "invalid_numbers": 0
    },
    "sender_id": "Texin",
    "units_used": 3,
    "total_cost": 0.9,
    "new_balance": 86,
    "message_ids": {
        "254759924977": "API-1768206118",
        "254725095094": "API-1768206119",
        "254700000001": "API-1768206120"
    },
    "invalid_numbers": [],
    "failed_recipients": {},
    "simulation_mode": false
}

Check Status

Check the delivery status of a sent SMS message.

POST /api/check_status
Request Parameters
Parameter Type Required Description
api_key String Yes Your API authentication key
message_id String Yes Message ID returned from send_sms or send_bulk_sms
Request Example
{
    "api_key": "your_api_key_here",
    "message_id": "API-1768206116"
}
Response Example
{
    "success": true,
    "message_id": "API-1768206116",
    "recipient": "254759924977",
    "sender_id": "Texin",
    "status": "sent",
    "units_used": 1,
    "cost": "0.30",
    "created_at": "2026-01-12 11:21:56",
    "sent_at": "2026-01-12 11:21:56",
    "delivered_at": null,
    "error_message": null,
    "gateway_response": {
        "status": "success",
        "mobile": "254759924977",
        "invalidMobile": "",
        "transactionId": "386817568305333146",
        "statusCode": "200",
        "reason": "success",
        "msgId": "",
        "requestTime": "2026-01-12 11:21:56"
    },
    "message_preview": "Test SMS at 11:21:55"
}

Get Balance

Get your current account balance and information.

POST /api/get_balance
Request Parameters
Parameter Type Required Description
api_key String Yes Your API authentication key
Request Example
{
    "api_key": "your_api_key_here"
}
Response Example
{
    "success": true,
    "user_id": 12,
    "username": "testuser",
    "email": "test@example.com",
    "sms_balance": 86,
    "default_sender_id": "Texin",
    "sms_cost_per_unit": "0.30",
    "timestamp": "2026-01-12 11:21:55"
}

Error Codes

HTTP Code Error Type Description
400 Bad Request Invalid request parameters or missing required fields
401 Unauthorized Invalid or missing API key
403 Forbidden Account inactive or insufficient permissions
404 Not Found Endpoint not found or message ID not found
405 Method Not Allowed Wrong HTTP method used for endpoint
500 Internal Server Error Server error or SMS gateway failure

Testing Tools

cURL Examples

Get Balance
curl -X POST https://texin.hotspotbillingsystem.co.ke/api/get_balance \
  -H "Content-Type: application/json" \
  -d '{"api_key":"your_api_key_here"}'
Send SMS
curl -X POST https://texin.hotspotbillingsystem.co.ke/api/send_sms \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    "recipient": "254759924977",
    "message": "Test message from cURL",
    "sender_id": "Texin"
  }'

PowerShell Examples

Get Balance
$body = '{"api_key":"your_api_key_here"}'
$response = Invoke-RestMethod -Uri "https://texin.hotspotbillingsystem.co.ke/api/get_balance" `
  -Method Post `
  -Body $body `
  -ContentType "application/json"
$response | ConvertTo-Json
Send SMS
$body = '{
    "api_key": "your_api_key_here",
    "recipient": "254759924977",
    "message": "Test from PowerShell",
    "sender_id": "Texin"
}'
$response = Invoke-RestMethod -Uri "https://texin.hotspotbillingsystem.co.ke/api/send_sms" `
  -Method Post `
  -Body $body `
  -ContentType "application/json"
$response | ConvertTo-Json

Python Examples

Get Balance
import requests
import json

url = "https://texin.hotspotbillingsystem.co.ke/api/get_balance"
payload = {"api_key": "your_api_key_here"}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print(json.dumps(response.json(), indent=2))
Send SMS
import requests
import json

url = "https://texin.hotspotbillingsystem.co.ke/api/send_sms"
payload = {
    "api_key": "your_api_key_here",
    "recipient": "254759924977",
    "message": "Test from Python",
    "sender_id": "Texin"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)
print(json.dumps(response.json(), indent=2))

Frequently Asked Questions

We accept two formats: 2547XXXXXXXX (12 digits) or 07XXXXXXXX (10 digits). The API will automatically convert 07 numbers to 254 format.

Messages are charged per SMS unit. 1 unit = 160 characters. Messages longer than 160 characters are split into multiple SMS units (153 characters per subsequent SMS).

The default sender ID is "Texin". Other sender IDs may be available depending on your account. Contact support to register additional sender IDs.

Yes, to prevent abuse. The current limit is 100 requests per minute per API key. Contact support if you need higher limits.

Enable simulation mode in your account settings. In simulation mode, API calls will simulate SMS sending without actually sending messages or charging your account.
Need Help?

If you encounter any issues or have questions about the API, please:

  • Check the error messages in the API responses
  • Verify your API key is correct and your account is active
  • Ensure phone numbers are in the correct format
  • Contact support at rayprotechsolutions@gmail.com for assistance