SMS API Documentation

This documentation provides all the necessary details to integrate your platform with our SMS system, allowing you to send bulk messages and manage your unit balance programmatically using your unique API key.

Authentication

All requests to the API must be authenticated. You must include your unique API Key in every request, either in the custom **`X-Api-Key`** header (preferred) or as a query parameter.

YOUR_API_KEY_HERE

Method	Header/Parameter	Value
Header	X-Api-Key	`YOUR_API_KEY_HERE` (Preferred method)
Query	api_key	`YOUR_API_KEY_HERE` (Alternative)

Note: If the API key is missing or invalid, a `401 Unauthorized` response will be returned.

1. Send SMS Message

This is the primary endpoint for sending one or more messages. The system handles unit calculation and deduction automatically. Ensure you have sufficient units before submitting.

Endpoint: POST /api/sms/send Content Type: application/json

Request Body Parameters

Parameter	Type	Required	Description
to	string	Yes	Comma-separated list of recipient phone numbers (e.g., `+1234567890,2345678901`). Numbers must be 7 to 15 digits.
content	string	Yes	The message content (Max 1000 characters).
from	string	No	The custom Sender ID/Name (Max 11 characters, optional). Uses a default if not provided.

Example Request

$ curl -X POST "https://skezzole.com.ng/api/sms/send" \
      -H "Content-Type: application/json" \
      -H "X-Api-Key: YOUR_API_KEY_HERE" \
      -d '{
          "to": "2348012345678,2348098765432",
          "content": "This is a test message from my reseller account!",
          "from": "MyCompany"
      }'

const API_KEY = 'YOUR_API_KEY_HERE';
const API_URL = 'https://skezzole.com.ng/api/sms/send';

const data = {
    to: '2348012345678,2348098765432',
    content: 'This is a test message from my reseller account!',
    from: 'MyCompany'
};

fetch(API_URL, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': API_KEY
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));

<?php
$apiKey = 'YOUR_API_KEY_HERE';
$apiUrl = 'https://skezzole.com.ng/api/sms/send';

$payload = json_encode([
    'to' => '2348012345678,2348098765432',
    'content' => 'This is a test message from my reseller account!',
    'from' => 'MyCompany'
]);

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Api-Key: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
?>

Example Success Response (HTTP 200)

{
    "status": "success",
    "message": "SMS request processed.",
    "total_recipients": 2,
    "units_deducted": 2,
    "messages_sent": 2,
    "failed_recipients": [],
    "new_balance": 198.00,
    "request_id": 145
}

Example Error Response (HTTP 403)

Returned when the API key is valid, but the user has **Insufficient Units**.

{
    "status": "error",
    "message": "Insufficient SMS units.",
    "available_units": 10.00,
    "required_units": 12
}

2. Check Unit Balance

Use this simple GET endpoint to quickly retrieve your current available SMS unit balance before initiating a large send.

Endpoint: GET /api/user/balance

Example Request

$ curl -X GET "https://skezzole.com.ng/api/user/balance" \
      -H "X-Api-Key: YOUR_API_KEY_HERE"

const API_KEY = 'YOUR_API_KEY_HERE';
const API_URL = 'https://skezzole.com.ng/api/user/balance';

fetch(API_URL, {
    method: 'GET',
    headers: {
        'X-Api-Key': API_KEY
    }
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));

<?php
$apiKey = 'YOUR_API_KEY_HERE';
$apiUrl = 'https://skezzole.com.ng/api/user/balance';

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
?>

Example Success Response (HTTP 200)

{
    "status": "success",
    "message": "Current SMS unit balance.",
    "available_units": 198.00
}

3. Check Message Status

After sending a message, use the returned **`request_id`** to poll this endpoint for the delivery status of the entire batch and individual recipients.

Endpoint: GET /api/sms/status/{request_id}

URL Parameters

Parameter	Type	Required	Description
request_id	integer	Yes	The unique ID returned from a successful `POST /api/sms/send` request.

Example Request

$ curl -X GET "https://skezzole.com.ng/api/sms/status/145" \
      -H "X-Api-Key: YOUR_API_KEY_HERE"

const API_KEY = 'YOUR_API_KEY_HERE';
const REQUEST_ID = '145';
const API_URL = `https://skezzole.com.ng/api/sms/status/${REQUEST_ID}`;

fetch(API_URL, {
    method: 'GET',
    headers: {
        'X-Api-Key': API_KEY
    }
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));

<?php
$apiKey = 'YOUR_API_KEY_HERE';
$requestId = '145';
$apiUrl = 'https://skezzole.com.ng/api/sms/status/' . $requestId;

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
?>

Example Success Response (HTTP 200)

{
    "status": "success",
    "message": "Message status retrieved.",
    "request_id": 145,
    "submitted_at": "2025-10-02T19:51:00Z",
    "content": "This is a test message from my reseller account!",
    "summary": {
        "total_recipients": 2,
        "sent": 2,
        "delivered": 1,
        "failed": 1
    },
    "recipients": [
        {
            "number": "2348012345678",
            "status": "Delivered",
            "gateway_ref": "ref_abc123"
        },
        {
            "number": "2348098765432",
            "status": "Failed",
            "gateway_ref": "ref_def456"
        }
    ]
}

Error Responses

**HTTP 404 Not Found:** Returned if the `request_id` does not exist in the database.
**HTTP 403 Forbidden:** Returned if the authenticated user (via API Key) attempts to view a message that they did not submit.