API Docs / Data

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

  1. Fetch the current data product catalogue with GET.
  2. Submit a data purchase request with POST using one of the returned network and amount combinations.
  3. SIMcloud queues the request and returns a request_id.
  4. Poll the same endpoint with GET until the status changes from queued or pending to a final status.
  5. Only orders that belong to the authenticated account can be queried.
  6. The same MSISDN and amount cannot be ordered again within 5 minutes. Duplicate requests inside that window return 409.

Supported Data Networks

Data Bundle Validation

The amount must match a valid bundle sell value configured in SIMcloud for the selected network. Use the product catalogue call before ordering if you need the current available bundle list.

Endpoints

1. List Data Products

GET

Returns data bundle products currently configured for API ordering. Without query parameters, GET returns all data products. Add network to filter the catalogue.

Query Parameters

Parameter Type Required Description
network string No Optional network name or internal code such as mtn or pd-mtn.

Example Request

GET https://simcloud.co.za/api/data.php?products=1
GET https://simcloud.co.za/api/data.php?products=1&network=mtn

Success Response

{
    "status": "success",
    "service": "data",
    "count": 2,
    "products": [
        {
            "product_id": 18,
            "network": "pd-mtn",
            "network_name": "MTN",
            "description": "1GB-R85",
            "groupname": "30-day Data Bundle",
            "amount": 85,
            "sellvalue": 85
        }
    ]
}

2. 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."
}

3. 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 to query an order. Without request_id or orderno, GET returns the product catalogue.

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

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