A data-bundle distribution platform can keep employees, field devices and managed SIM cards connected without asking an operator to buy each bundle manually. The SIMcloud Data API provides the live product catalogue, queue-based orders and status lookup; your platform controls eligibility, network selection, approval and reconciliation.
Understand why data is not airtime
Airtime accepts a rand amount. Data uses network-specific bundle products. Your application should fetch the current catalogue and let the authorised user select a valid bundle for the detected network.
Do not invent a data bundle from a rand value. Fetch /api/data.php?products=1 and use the returned network and sell value. Product descriptions, values and availability can change.
Design the distribution workflow
- Identify the employee, device or managed SIM.
- Confirm or refresh its current network.
- Load data products filtered for that network.
- Apply programme rules to the available products.
- Approve the recipient, bundle and budget.
- Create a unique local order.
- Submit to SIMcloud and store the returned request ID.
- Poll until delivered or failed.
- Reconcile the result to the allowance, project or device.
Fetch the live data products
GET https://simcloud.co.za/api/data.php?products=1&network=mtn
Authorization: Bearer YOUR_API_TOKENThe product response includes product_id, internal network, network name, description, group name, amount and sell value. Store a short-lived catalogue cache with its refresh time, but validate again when stale or before an important release.
Filter products for your programme
Your application might allow only:
- 30-day bundles rather than promotional products.
- A maximum monthly value per employee.
- Specific products for routers, tablets or telemetry devices.
- A standard bundle per job role.
- Manual approval above a threshold.
Apply these rules to the live SIMcloud catalogue. Do not create a second, permanently hard-coded price list.
Submit the selected data order
POST https://simcloud.co.za/api/data.php
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
{
"msisdn": "0821234567",
"network": "pd-mtn",
"amount": 85.00,
"reference": "FIELD-DATA-2026-07-000184"
}Use the network and sell value returned by the selected catalogue product. The API also accepts sellvalue as an alias for amount.
Persist the HTTP 201 response, especially request_id, before the worker finishes.
Prevent duplicate data orders
The Data API returns HTTP 409 when the same MSISDN and amount is ordered inside five minutes. Add your own local protection based on the allowance event or client reference.
Do not retry a 409 automatically. Reconcile the original request. A later duplicate can allocate the same bundle twice even if the second call no longer falls inside five minutes.
Poll to a final state
GET https://simcloud.co.za/api/data.php?request_id=1527246
Authorization: Bearer YOUR_API_TOKENQueued and pending are non-final. Delivered means the bundle order completed successfully; failed is final. Keep the platform order number and final order fields returned by the status response for support and reporting.
Connect the platform to SIM inventory
A managed-SIM platform should store the number, current network, last lookup time, assigned user/device, approved bundle profile and recharge history. Refresh the network before ordering when the stored result is missing or too old for the risk of the transaction.
Monitor wallet and programme budget
Use SIMcloud wallet balance as an operational pre-check and your own programme ledger as the approval authority. Alert before the wallet reaches a level that will interrupt scheduled recharges. Remember that the Balance API returns the last known balance and does not reserve value.
Reconcile distributed data
| Report group | Required evidence |
|---|---|
| Approved | Recipient/device, product rule, value and approver. |
| Submitted | Local reference and SIMcloud request ID. |
| Delivered | Final status, platform order number and completion time. |
| Failed | Error, billing result and resolution owner. |
| Duplicate blocked | Original local and SIMcloud request references. |
Frequently asked questions
Can the Data API accept any rand amount?
Select a valid product from the current data catalogue and use its returned network and sell value.
Can I filter the catalogue by network?
Yes. Use products=1 with the optional network query parameter.
How do I handle number portability?
Use a current Network Lookup API result rather than relying permanently on the number prefix.
What does HTTP 409 mean?
The same MSISDN and amount was ordered inside the documented five-minute window.
When is a data order complete?
Delivered or failed is final. Queued and pending should be polled later.