API Docs / AI & Codex

Overview SMS Airtime Data Electricity Balance Network Lookup AI & Codex OpenAPI

AI and Codex Integration

Simply paste this page into your AI agent. It is designed so tools like Codex, Claude, and ChatGPT can understand how SIMcloud works and how to connect to it.

SIMcloud can be connected to ChatGPT, Codex, and other MCP-compatible tools so that users can work with their own SIMcloud account through AI-assisted workflows.

This integration uses OAuth for user sign-in and an MCP endpoint for tool calls.

What This Enables

Check SIMcloud wallet balance from an AI assistant.
Look up the mobile network for South African numbers.
Send SMS messages from the authenticated SIMcloud account.
Create airtime, data, and electricity orders through the user's own wallet and API permissions.

Connection Endpoints

Component	URL
MCP endpoint	https://simcloud.co.za/api/mcp.php
Protected resource metadata	https://simcloud.co.za/.well-known/oauth-protected-resource
Authorization server metadata	https://simcloud.co.za/.well-known/oauth-authorization-server
Dynamic client registration	https://simcloud.co.za/oauth/register.php
Authorization endpoint	https://simcloud.co.za/oauth/authorize.php
Token endpoint	https://simcloud.co.za/oauth/token.php
OpenAPI specification	https://simcloud.co.za/api/openapi.yaml

Integration Brief For Codex And Similar Tools

This section is intended for AI coding tools that need exact integration context.

SIMcloud exposes an OAuth-protected MCP server at https://simcloud.co.za/api/mcp.php.
The MCP server is the preferred entry point for AI assistants that support MCP and OAuth.
The OAuth metadata endpoints are:
- https://simcloud.co.za/.well-known/oauth-protected-resource
- https://simcloud.co.za/.well-known/oauth-authorization-server
The dynamic client registration endpoint is https://simcloud.co.za/oauth/register.php.
The machine-readable REST contract is https://simcloud.co.za/api/openapi.yaml.
Users authenticate with their own SIMcloud account. Do not assume a shared API token.
After OAuth sign-in, the MCP server maps the OAuth access token to the connected user's SIMcloud API token internally.
The current documented SIMcloud capabilities are wallet balance, network lookup, SMS, airtime, data, and prepaid electricity.

Authentication Model

Users do not share a single SIMcloud token with everyone. Each user authenticates with their own SIMcloud account.

PKCE is required. Use code_challenge_method=S256.

The AI tool registers or uses an OAuth client.
The user signs in to SIMcloud and approves access.
SIMcloud issues an OAuth access token.
The AI tool sends that token to the SIMcloud MCP endpoint.
The MCP endpoint maps that OAuth token to the user's SIMcloud API token internally.

This means tool calls run against the connected user's own SIMcloud account, wallet, and permissions.

MCP Transport

The SIMcloud MCP endpoint uses HTTPS JSON-RPC requests over standard HTTP POST.

It does not use Server-Sent Events (SSE). Tools should connect to https://simcloud.co.za/api/mcp.php as an HTTP MCP endpoint.

OAuth Scope

The current OAuth integration uses a single scope:

api

This scope gives the connected tool access to the SIMcloud capabilities exposed through the MCP server and documented API surface, including balance checks, network lookup, SMS, airtime, data, and prepaid electricity actions.

There are not currently separate public scopes such as balance:read or sms:send. Assistants and developers should assume the integration uses the single api scope unless SIMcloud publishes narrower scopes in future.

OAuth Response Example

A successful token exchange returns JSON in this shape:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api"
}

Access tokens currently expire after 3600 seconds. Refresh tokens are supported and should be used to continue an existing connection without asking the user to sign in again.

MCP Tools

The SIMcloud MCP server currently exposes these tool names and arguments:

Tool	Required arguments	Optional arguments
`get_wallet_balance`	None	None
`lookup_network`	`msisdn`	None
`send_sms`	`recipient`, `message`	None
`get_sms_status`	`sms_id`	None
`create_airtime_order`	`msisdn`, `network`, `amount`, `reference`	None
`get_airtime_order`	None	`request_id`, `orderno`
`create_data_order`	`msisdn`, `network`, `amount`, `reference`	None
`get_data_order`	None	`request_id`, `orderno`
`create_electricity_order`	`meter_number`, `amount`, `client_reference`, `recipient`	None
`get_electricity_order`	None	`order_id`, `client_reference`, `order_reference_id`

MCP Response Shape

A successful MCP tool call returns JSON-RPC with a tool result and structured content. A typical success shape looks like this:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "SIMcloud returned HTTP 200."
      }
    ],
    "structuredContent": {
      "ok": true,
      "status": 200,
      "data": {}
    }
  },
  "id": 1
}

Auth or validation failures still return JSON-RPC, but the tool result contains a non-success structuredContent.status such as 401, 400, 409, or 503 depending on the request outcome.

Using SIMcloud In Codex, Claude, And ChatGPT

If you want an AI assistant to work with your SIMcloud account, start by sharing this guide page:

https://simcloud.co.za/api/ai.html

You can paste that link into Codex, Claude, or ChatGPT and ask the assistant to help you connect SIMcloud or build against the SIMcloud API.

Copy-Paste Prompt For AI Assistants

Please read https://simcloud.co.za/api/ai.html first.

Then use these SIMcloud integration rules:
- Prefer the MCP endpoint at https://simcloud.co.za/api/mcp.php when MCP tool access is supported.
- Use the OAuth metadata endpoints linked on the AI guide page to understand sign-in and token handling.
- Use https://simcloud.co.za/api/openapi.yaml as the source of truth for the REST API contract.
- Assume each user must authenticate with their own SIMcloud account.
- Do not assume shared credentials.
- The available SIMcloud capabilities are balance, network lookup, SMS, airtime, data, and prepaid electricity.

Help me connect or integrate SIMcloud based on those rules.

You can use that prompt in Codex, Claude, or ChatGPT.

What To Send

For a customer setup or overview, send this page: https://simcloud.co.za/api/ai.html
For raw API details, send the OpenAPI spec: https://simcloud.co.za/api/openapi.yaml
For direct MCP connection details, send the MCP endpoint: https://simcloud.co.za/api/mcp.php

Example Prompts

Codex

Please read https://simcloud.co.za/api/ai.html and help me connect my SIMcloud account.

Claude

Use https://simcloud.co.za/api/ai.html to understand the SIMcloud API and show me how to use it.

ChatGPT

Read https://simcloud.co.za/api/ai.html and help me set up SIMcloud for balance checks, SMS, and recharges.

What The Assistant Can Help With

Check your SIMcloud wallet balance without logging into the portal manually.
Look up the mobile network for South African numbers before sending airtime, data, or SMS campaigns.
Send single SMS messages or help prepare bulk SMS workflows using your SIMcloud account.
Create airtime recharges for customer numbers using your authenticated SIMcloud wallet.
Create data bundle recharges using the SIMcloud Data API.
Create prepaid electricity orders using the SIMcloud Electricity API.
Check the status of existing SMS, airtime, data, or electricity requests.
Explain which SIMcloud API endpoint to use for a specific task and generate example requests.
Help developers build SIMcloud features into websites, apps, back-office systems, and automated workflows.

Failure And Error Handling Notes

OAuth failure: If sign-in, consent, or token exchange fails, retry the connection flow and confirm that the client, redirect URI, and SIMcloud login details are correct.
Invalid or expired token: Reconnect the SIMcloud account or refresh the OAuth token if the client supports token refresh.
MCP endpoint unavailable: If the MCP endpoint is temporarily unavailable, retry later and fall back to the documented REST API where appropriate.
Insufficient wallet balance: Recharge, SMS, data, and electricity requests depend on the connected SIMcloud wallet having enough available funds.
Validation errors: Invalid MSISDNs, missing required fields, unsupported request values, or malformed payloads should be corrected before retrying.
Asynchronous orders: Airtime, data, and electricity flows may require status checks after submission rather than assuming an immediate final result.

SIMcloud Request Rules

MSISDN formats: The current docs show both 0821234567 and +27821234567 depending on the endpoint. Follow the endpoint-specific examples until SIMcloud publishes a stricter normalization rule.
Networks: Airtime and data requests accept friendly network names or internal codes. The current public docs show examples such as mtn and vodacom.
Data bundles: The current public API is amount-based. Bundle selection is not published on this page as a separate catalog yet.
Electricity support: Electricity is supported through the SIMcloud Electricity API, but this page does not currently publish a municipality-by-municipality support list.
Duplicate orders: Airtime and data reject duplicate same-MSISDN-and-amount requests inside a 5-minute window and may return HTTP 409.
Insufficient funds: Airtime, data, SMS, and electricity requests depend on available wallet balance. Validation or balance failures are documented as HTTP 400 on the REST side.

Using SIMcloud With AI

SIMcloud can be used with Codex, Claude, and ChatGPT so that the assistant can help you work with your own SIMcloud account.

Share this guide page with the assistant, then ask it to help you connect SIMcloud or build a workflow around balance checks, SMS sending, airtime, data, or electricity orders.