SMS API Documentation

Base URL

https://simcloud.co.za/api/sms.php

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Endpoints

1. Send SMS

Send a new SMS message to a recipient.

POST Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
recipient	string	Yes	Phone number in South African format (+27XXXXXXXXX)
message	string	Yes	SMS content (max 459 characters)

Example Request

{
    "recipient": "+27821234567",
    "message": "Hello World!"
}

Success Response

{
    "status": "success",
    "message": "SMS queued successfully",
    "sms_id": "123456",
    "sms_count": 1,
    "timestamp": "2024-10-24 14:30:00"
}

Error Response

{
    "status": "error",
    "message": "Invalid recipient number, must be in the format +27XXXXXXXXX"
}

2. Check SMS Status

Query the status of a sent SMS message.

GET

Query Parameters

Parameter	Type	Required	Description
sms_id	integer	Yes	ID of the SMS message

Example Request

GET https://simcloud.co.za/api/sms.php?sms_id=123456

Success Response

{
    "sms_id": "123456",
    "status": "delivered"
}

Important Notes

Phone numbers must be in South African format (+27XXXXXXXXX)
Messages are limited to 459 characters
SMS credits are calculated based on message length:
- 1-160 characters: 1 credit
- 161-306 characters: 2 credits
- 307-459 characters: 3 credits
Status checks within 15 seconds of sending will return "queued" status
The API supports UTF-8 encoded messages

Statuses

queued
pending
sent
failed
delivered
staged
unknown

A status of "delivered" means the SMS has been received on the recipient handset.

Error Codes

Code	Description
400	Bad Request (invalid parameters)
401	Unauthorized (invalid or missing token)
404	Not Found (SMS ID doesn't exist)
500	Internal Server Error

For technical support, please contact our support team at customercare@freepaid.co.za.