API Docs / SMS

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

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

Statuses

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.