Build with SwiftSMS

Introduction

The SwiftSMS API allows developers to integrate SMS messaging directly into websites, mobile applications, business systems and other software.

You can use the API to send transactional messages, OTPs, notifications, alerts and bulk SMS without requiring users to log into the SwiftSMS dashboard.

Authentication

Every authenticated API request must include a valid SwiftSMS API key.

Send your API key using the X-API-Key HTTP header.

X-API-Key: sms_live_your_api_key_here
Content-Type: application/json

Quick Start

You can send your first SMS in a few simple steps.

Send SMS

Use the /api/send endpoint to send SMS messages.

{
    "type": "bulk",
    "phones": [
        "256700000001",
        "256700000002"
    ],
    "message": "Welcome to SwiftSMS Uganda."
}

OTP Messages

Use "type": "otp" when sending one-time passwords or other time-sensitive authentication messages.

Example

{
    "type": "otp",
    "phones": [
        "256700000001"
    ],
    "message": "Your SwiftSMS verification code is 482913."
}

If an immediate direct OTP delivery fails after available provider routes are attempted, the applicable SMS charge is automatically refunded.

Bulk SMS

Bulk SMS is designed for sending messages to multiple recipients such as customers, staff, members or subscribers.

{
    "type": "bulk",
    "phones": [
        "256700000001",
        "256700000002",
        "256700000003"
    ],
    "message": "Your appointment is confirmed."
}

Scheduled SMS

You can schedule a message for future delivery by setting send_type to scheduled and providing a future scheduled_at value.

Example

{
    "type": "bulk",
    "phones": [
        "256700000001"
    ],
    "message": "Your appointment is tomorrow at 10:00 AM.",
    "send_type": "scheduled",
    "scheduled_at": "2026-09-10 09:00:00"
}

API Test

The API also provides a simple test endpoint that can be used to verify API connectivity.

GET https://swiftsmsuganda.com/api/test

Request Parameters

The following parameters are supported by the SMS sending endpoint.

Responses

API responses are returned as JSON.

Successful Request

{
    "status": "success",
    "message": "SMS queued successfully",
    "campaign_id": 12345
}

Direct OTP Response

Immediate OTP requests may return delivery information directly when they are processed immediately.

{
    "status": "success",
    "campaign_id": 12345,
    "completed": true,
    "otp": true,
    "direct": true,
    "successful": 1,
    "failed": 0
}

Error Handling

When a request cannot be processed, the API returns a JSON error response.

Example Error

{
    "status": "error",
    "message": "Message cannot be empty"
}

cURL Example

You can test the API from a terminal using cURL.

curl -X POST "https://swiftsmsuganda.com/api/send" \
-H "X-API-Key: sms_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
    "type": "bulk",
    "phones": [
        "256700000001"
    ],
    "message": "Hello from SwiftSMS Uganda."
}'

PHP Example

$apiKey = 'sms_live_your_api_key_here';

$data = [
    'type' => 'bulk',
    'phones' => [
        '256700000001'
    ],
    'message' => 'Hello from SwiftSMS Uganda.'
];

$ch = curl_init('https://swiftsmsuganda.com/api/send');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
]);

$response = curl_exec($ch);

curl_close($ch);

$result = json_decode($response, true);

print_r($result);

Node.js / JavaScript Example

const response = await fetch(
    'https://swiftsmsuganda.com/api/send',
    {
        method: 'POST',
        headers: {
            'X-API-Key': 'sms_live_your_api_key_here',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            type: 'bulk',
            phones: [
                '256700000001'
            ],
            message: 'Hello from SwiftSMS Uganda.'
        })
    }
);

const result = await response.json();

console.log(result);

Python Example

import requests

api_key = "sms_live_your_api_key_here"

payload = {
    "type": "bulk",
    "phones": [
        "256700000001"
    ],
    "message": "Hello from SwiftSMS Uganda."
}

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

response = requests.post(
    "https://swiftsmsuganda.com/api/send",
    json=payload,
    headers=headers
)

print(response.json())

API Keys

API keys provide secure access to the SwiftSMS API on behalf of your account.

Security Recommendations

• Keep API keys on your server.
• Never commit API keys to public Git repositories.
• Do not expose API keys in frontend JavaScript.
• Regenerate a key if you believe it has been compromised.
• Disable keys that are no longer required.

Wallet & Billing

SMS usage is charged against your SwiftSMS account wallet.

SMS billing is based on message segments. A message containing multiple SMS segments consumes the corresponding number of units.

Message Segments

Longer messages can use more than one SMS segment. Your account is charged according to the number of segments used for delivery.

What can you build?