SIMcloud OpenAPI Specification
This page displays the current OpenAPI spec in-browser.
Use the raw YAML URL for agents, generated clients, and direct spec ingestion: https://simcloud.co.za/api/openapi.yaml
openapi: 3.0.3
info:
title: SIMcloud API
version: 1.0.0
description: |
Token-authenticated SIMcloud API for SMS, airtime, data, VAS, electricity,
wallet balance, and network lookup.
servers:
- url: https://simcloud.co.za
security:
- bearerAuth: []
tags:
- name: SMS
- name: Airtime
- name: Data
- name: VAS
- name: Electricity
- name: Balance
- name: Network Lookup
paths:
/api/sms.php:
post:
tags: [SMS]
summary: Queue an SMS
operationId: sendSms
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [recipient, message]
properties:
recipient:
type: string
example: "+27821234567"
message:
type: string
example: "Hello World!"
responses:
'200':
description: SMS queued
'400':
description: Validation error
'401':
description: Unauthorized
get:
tags: [SMS]
summary: Query SMS status
operationId: getSmsStatus
parameters:
- in: query
name: sms_id
required: true
schema:
type: integer
responses:
'200':
description: SMS status
'404':
description: SMS not found
/api/airtime.php:
post:
tags: [Airtime]
summary: Queue an airtime order
description: The same MSISDN and amount cannot be ordered again within 5 minutes. Duplicate requests inside that window return HTTP 409.
operationId: createAirtimeOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [msisdn, network, amount, reference]
properties:
msisdn:
type: string
example: "0821234567"
network:
type: string
description: Accepts friendly names or internal codes.
example: "mtn"
amount:
type: number
format: float
example: 10.00
reference:
type: string
example: "Airtime for John"
responses:
'201':
description: Airtime order queued
'400':
description: Validation or balance error
'401':
description: Unauthorized
'409':
description: Duplicate order within the 5-minute rule window
get:
tags: [Airtime]
summary: Query an airtime order
operationId: getAirtimeOrder
parameters:
- in: query
name: request_id
required: false
schema:
type: integer
- in: query
name: orderno
required: false
schema:
type: string
responses:
'200':
description: Airtime order status
'404':
description: Order not found
/api/data.php:
post:
tags: [Data]
summary: Queue a data order
description: The same MSISDN and amount cannot be ordered again within 5 minutes. Duplicate requests inside that window return HTTP 409.
operationId: createDataOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [msisdn, network, amount, reference]
properties:
msisdn:
type: string
example: "0821234567"
network:
type: string
description: Accepts friendly names or internal codes.
example: "vodacom"
amount:
type: number
format: float
example: 25.00
sellvalue:
type: number
format: float
description: Alias for amount.
reference:
type: string
example: "Data for John"
responses:
'201':
description: Data order queued
'400':
description: Validation or balance error
'401':
description: Unauthorized
'409':
description: Duplicate order within the 5-minute rule window
get:
tags: [Data]
summary: List data products or query a data order
description: Without request_id or orderno, returns the current data bundle product catalog. Add network to filter the catalog. With request_id or orderno, returns the authenticated account's data order status.
operationId: getDataOrder
parameters:
- in: query
name: products
required: false
description: Optional flag for product catalog reads. Bare GET also returns the catalog when request_id and orderno are not supplied.
schema:
type: boolean
- in: query
name: network
required: false
description: Optional network filter for product catalog reads. Accepts friendly names or internal codes.
schema:
type: string
- in: query
name: request_id
required: false
schema:
type: integer
- in: query
name: orderno
required: false
schema:
type: string
responses:
'200':
description: Data product catalog or data order status
'400':
description: Invalid catalog filter or order query
'404':
description: Order not found
/api/vas.php:
get:
tags: [VAS]
summary: List VAS products or query a VAS order
description: Without query parameters, returns the active VAS product catalog. With order_id or transaction_id, returns an API-created VAS order owned by the authenticated account.
operationId: getVas
parameters:
- in: query
name: order_id
required: false
schema:
type: integer
- in: query
name: transaction_id
required: false
schema:
type: string
format: uuid
responses:
'200':
description: VAS catalog or VAS order status
'401':
description: Unauthorized
'404':
description: Order not found
post:
tags: [VAS]
summary: Queue a VAS voucher order
operationId: createVasOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [amount, reference]
properties:
product_id:
type: integer
description: SIMcloud VAS product ID returned by the catalog endpoint. Required if voucher_type is not supplied.
example: 12
voucher_type:
type: string
description: Exact voucher type or slug returned by the catalog endpoint. Required if product_id is not supplied.
example: "checkers"
amount:
type: number
format: float
example: 100.00
reference:
type: string
maxLength: 200
example: "INV-10045"
responses:
'201':
description: VAS order queued
'400':
description: Validation, denomination, or balance error
'401':
description: Unauthorized
/api/electricity.php:
post:
tags: [Electricity]
summary: Submit an electricity order
operationId: createElectricityOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [meter_number, amount, client_reference, recipient]
properties:
meter_number:
type: string
example: "01234567890"
amount:
type: number
format: float
example: 150.00
client_reference:
type: string
example: "INV-10045"
recipient:
type: string
example: "0821234567"
send_sms:
type: boolean
example: true
sms_company_name:
type: string
example: "acme power"
responses:
'201':
description: Electricity order accepted
'400':
description: Validation or balance error
'401':
description: Unauthorized
'503':
description: Electricity unavailable
get:
tags: [Electricity]
summary: Check an electricity meter or query an electricity order
operationId: getElectricityOrder
parameters:
- in: query
name: meter_number
required: false
schema:
type: string
description: Meter number to validate before placing an order. When supplied, the endpoint returns meter support details instead of order status. A supplier internal error returns status unknown and supported null; retry later rather than treating the meter as unsupported.
- in: query
name: order_id
required: false
schema:
type: integer
- in: query
name: client_reference
required: false
schema:
type: string
- in: query
name: order_reference_id
required: false
schema:
type: string
responses:
'200':
description: Meter support details, pending order status, or completed electricity voucher details
'400':
description: Missing or invalid query parameters
'404':
description: Order not found
'502':
description: Electricity meter validation request failed
'503':
description: Electricity meter validation unavailable
/api/balance.php:
get:
tags: [Balance]
summary: Get wallet balance
operationId: getWalletBalance
responses:
'200':
description: Last known wallet balance
'401':
description: Unauthorized
/api/network.php:
get:
tags: [Network Lookup]
summary: Look up a mobile network
operationId: lookupNetwork
parameters:
- in: query
name: msisdn
required: true
schema:
type: string
example: "0821234567"
responses:
'200':
description: Network found
'400':
description: Invalid msisdn
'401':
description: Unauthorized
'404':
description: Number does not match any network
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Token