Data API Documentation

Base URL

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

Authentication

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

Authorization: Bearer YOUR_API_TOKEN

How It Works

Submit a data purchase request with POST.
SIMcloud queues the request and returns a request_id.
Poll the same endpoint with GET until the status changes from queued or pending to a final status.
Only orders that belong to the authenticated account can be queried.
The same MSISDN and amount cannot be ordered again within 5 minutes. Duplicate requests inside that window return 409.

Supported Data Networks

mtn or pd-mtn
cellc, cell-c, cell c or pd-cellc
vodacom or pd-vodacom
telkom, heita or pd-heita

Data Bundle Validation

The amount must match a valid bundle sell value configured in SIMcloud for the selected network.

Endpoints

1. Place Data Order

POST Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
msisdn	string	Yes	South African mobile number to recharge.
network	string	Yes	Network name or internal code such as `mtn` or `pd-mtn`.
amount	number	Yes	Bundle sell value configured for that network.
reference	string	Yes	Your own reference for the request.

The API also accepts sellvalue as an alias for amount.

Example Request

{
    "msisdn": "0821234567",
    "network": "pd-mtn",
    "amount": 25.00,
    "reference": "Data for John"
}

Success Response

{
    "status": "success",
    "message": "Data order queued successfully",
    "request_id": 1527246,
    "service": "data",
    "msisdn": "+27821234567",
    "network": "pd-mtn",
    "amount": 25,
    "reference": "Data for John",
    "queue_status": "queued",
    "timestamp": "2026-04-16 16:05:00"
}

Insufficient Balance Response

{
    "status": "error",
    "message": "Insufficient balance. Please top up your account.",
    "required_balance": 25,
    "available_balance": 10
}

Duplicate Order Response

{
    "status": "error",
    "message": "An order for the same MSISDN and amount has been placed in the last 5 minutes."
}

2. Query Data Order

GET

Query Parameters

Parameter	Type	Required	Description
request_id	integer	No	Queue request ID returned by the POST request.
orderno	string	No	Platform order number once it has been allocated.

At least one of the two query parameters is required.

Example Request

GET https://simcloud.co.za/api/data.php?request_id=1527246

Delivered Response

{
    "status": "delivered",
    "service": "data",
    "request_id": 1527246,
    "msisdn": "+27821234567",
    "network": "pd-mtn",
    "amount": 25,
    "reference": "Data for John",
    "platform_order_number": "2233445566",
    "queue_status": "Order Placed",
    "final_order_id": 1395229,
    "final_order_status": "delivered",
    "error": "Success",
    "created_at": "2026-04-16 16:05:00",
    "updated_at": "2026-04-16 16:06:20"
}

Statuses

queued: Request is stored locally and waiting to be placed.
pending: Platform order number exists, but final delivery status is not back yet.
delivered: Data order completed successfully.
failed: Data order failed.

Error Codes

Code	Description
400	Bad Request (missing or invalid parameters)
401	Unauthorized (invalid or missing token)
404	Order not found for this account
409	Duplicate order detected within the 5-minute rule window