Scholar SMS Logo
Scholar SMS
API Documentation
Getting Started

Welcome to the OLIN SMS API documentation. Our API allows you to send SMS messages, manage your account balance, and track message delivery programmatically.

Base URL

http://sms.scholar.ke/api

API Key Required

To use the API, you need to register for an account or login to get your API key.

Authentication

The API uses token-based authentication. You need to login first to get an authentication token, then include it in subsequent requests.

1. Login to Get Token
curl -X POST http://sms.scholar.ke/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'

Response

{
  "code": 200,
  "state": "success",
  "data": {
    "user": { ... },
    "token": "1|abc123...",
    "message": "Login successful"
  }
}
2. Use Token in Requests

Include the token in the Authorization header for all protected endpoints: 

Authorization: Bearer YOUR_TOKEN_HERE
API Endpoints
Authentication
POST
/api/register

Register a new user account

POST
/api/login

Login and get authentication token

POST
/api/logout
Auth Required

Logout and revoke token

Balance & Payment
POST
/api/balance
Auth Required

Get your current SMS balance

POST
/api/topup
Auth Required

Initiate M-Pesa STK Push payment

Messaging
POST
/api/pool
Auth Required

Queue messages for sending (single or group)

POST
/api/messages
Auth Required

Retrieve messages with optional filtering

POST
/api/delivery
Auth Required

Get delivery reports for specific messages

Complete Code Examples
Send Single SMS

cURL

curl -X POST http://sms.scholar.ke/api/pool \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0712345678",
    "message": "Hello from OLIN SMS!",
    "mode": "single"
  }'

PHP (using Guzzle)

<?php
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'http://sms.scholar.ke/api/',
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'Content-Type' => 'application/json',
    ]
]);

$response = $client->post('pool', [
    'json' => [
        'to' => '0712345678',
        'message' => 'Hello from OLIN SMS!',
        'mode' => 'single'
    ]
]);

$result = json_decode($response->getBody(), true);
print_r($result);

JavaScript (using Fetch)

const sendSMS = async () => {
  const response = await fetch('http://sms.scholar.ke/api/pool', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '0712345678',
      message: 'Hello from OLIN SMS!',
      mode: 'single'
    })
  });

  const data = await response.json();
  console.log(data);
};

sendSMS();

Python (using Requests)

import requests

url = 'http://sms.scholar.ke/api/pool'
headers = {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'to': '0712345678',
    'message': 'Hello from OLIN SMS!',
    'mode': 'single'
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
Send Group SMS
curl -X POST http://sms.scholar.ke/api/pool \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [1, 2, 3],
    "message": "Bulk message to multiple groups",
    "mode": "group"
  }'
Check Balance
curl -X POST http://sms.scholar.ke/api/balance \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "code": 200,
  "state": "success",
  "data": {
    "balance": 1500,
    "account_number": "ABC123",
    "sender_id": "OLIN_SMS"
  }
}
Error Handling

All API responses follow a consistent format. Errors include detailed information to help you debug issues.

Error Response Format

{
  "code": 400,
  "state": "error",
  "data": {
    "message": "Invalid phone number format",
    "errors": {
      "phone": ["The phone field is required."]
    }
  }
}

Common HTTP Status Codes

200
Success
400
Bad Request (validation error)
401
Unauthorized (invalid or missing token)
404
Not Found
500
Server Error
Best Practices

Store your token securely

Never expose your API token in client-side code or public repositories.

Check balance before sending

Always verify you have sufficient balance before pooling messages.

Handle errors gracefully

Implement proper error handling and retry logic in your application.

Validate phone numbers

Ensure phone numbers are in valid Kenyan format (0712345678 or +254712345678).

Use HTTPS in production

Always use HTTPS to ensure secure communication with the API.

Need Help?

If you have questions or need assistance integrating with our API, please don't hesitate to reach out.

Contact Support