📚 API Documentation
Integrate InstadataGH with your applications
Base URL: https://instadatagh.com/api/v1
AUTH
Authentication
All API requests must be authenticated using your API key. Include your API key in the x-api-key header.
x-api-key: your_api_key_here
Get your API key from the API Settings page.
GET
/api/v1/balance
Get wallet balance
Retrieve your current wallet balance. Useful for pre-order validation.
Response Example
{
"success": true,
"balance": 150.50,
"currency": "GHS",
"name": "John Doe",
"timestamp": "2026-04-28T23:04:59.226Z"
}
cURL Example
curl -X GET https://instadatagh.com/api/v1/balance \ -H "x-api-key: your_api_key_here"
GET
/api/v1/offers
Get available offers
Retrieve all active data, airtime, and voice bundles available for each network.
Response Example
{
"success": true,
"offers": [
{
"name": "MTN Master Bundle",
"isp": "MTN",
"type": "Data",
"offerSlug": "mtn_master_bundle",
"volumes": [1, 2, 3, 4, 5, 6, 7, 8, 10, 15, 20, 25, 30, 40, 50]
}
]
}
POST
/api/v1/order/{network}
Place single order
Place an order for a single recipient. Network options: mtn, at, telecel
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Must be "single" |
| volume | integer | Yes | Data volume in GB |
| phone | string | Yes | Recipient phone (format: 233XXXXXXXXX) |
| offerSlug | string | Yes | Offer identifier from /offers endpoint |
| webhookUrl | string | Yes | URL to receive order status updates |
Request Example
{
"type": "single",
"volume": 2,
"phone": "233241234567",
"offerSlug": "mtn_master_bundle",
"webhookUrl": "https://yourdomain.com/webhook"
}
cURL Example
curl -X POST https://instadatagh.com/api/v1/order/mtn \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key_here" \
-d '{"type":"single","volume":2,"phone":"233241234567","offerSlug":"mtn_master_bundle","webhookUrl":"https://yourdomain.com/webhook"}'
POST
/api/v1/order/{network}
Place bulk order
Place orders for multiple recipients in a single request (max 100 items).
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Must be "bulk" |
| items | array | Yes | Array of {volume, recipient} objects |
| offerSlug | string | Yes | Offer identifier from /offers endpoint |
| webhookUrl | string | Yes | URL to receive order status updates |
Request Example
{
"type": "bulk",
"items": [
{"volume": 2, "recipient": "233241234567"},
{"volume": 5, "recipient": "233241234568"}
],
"offerSlug": "mtn_master_bundle",
"webhookUrl": "https://yourdomain.com/webhook"
}
GET
/api/v1/order/status/{identifier}
Check order status
Retrieve the status of a specific order using either the orderId or reference.
Order Statuses
pending
Order received, processing
processing
Being processed
delivered
Successfully delivered
failed
Delivery failed
Response Example
{
"success": true,
"order": {
"orderId": "ORD-000067",
"reference": "ORD-IB22OQws",
"status": "delivered",
"recipient": "233241234567",
"volume": 2,
"timestamp": "2025-04-05T10:35:00Z"
}
}
PHP
Integration Example
Complete PHP Integration Class
<?php
/**
* InstadataGH API Client for PHP
*/
class InstadataGHAPI {
private $api_key;
private $base_url = 'https://instadatagh.com/api/v1';
public function __construct($api_key) {
$this->api_key = $api_key;
}
private function request($method, $endpoint, $data = null) {
$ch = curl_init($this->base_url . $endpoint);
$headers = [
'Content-Type: application/json',
'x-api-key: ' . $this->api_key
];
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
if ($method === 'POST') {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
public function getBalance() {
return $this->request('GET', '/balance');
}
public function getOffers() {
return $this->request('GET', '/offers');
}
public function placeOrder($network, $orderData) {
return $this->request('POST', '/order/' . $network, $orderData);
}
public function getOrderStatus($identifier) {
return $this->request('GET', '/order/status/' . $identifier);
}
}
// Usage Example
$api = new InstadataGHAPI('your_api_key_here');
try {
// Check balance
$balance = $api->getBalance();
echo "Balance: " . $balance['balance'] . " GHS\n";
// Place order
$order = $api->placeOrder('mtn', [
'type' => 'single',
'volume' => 2,
'phone' => '233241234567',
'offerSlug' => 'mtn_master_bundle',
'webhookUrl' => 'https://yourdomain.com/webhook'
]);
print_r($order);
} catch (Exception $e) {
echo "Error: " . $e->getMessage();
}
?>
WEBHOOK
Order Status Updates
When you include a webhookUrl in your order request, we'll send POST requests to that URL whenever the order status changes.
Webhook Payload
{
"event": "order.status.updated",
"orderId": "ORD-000067",
"reference": "ORD-IB22OQws",
"status": "delivered",
"recipient": "233241234567",
"volume": 2,
"timestamp": "2025-04-05T10:35:00Z"
}
PHP Webhook Handler
<?php
// webhook.php
$input = file_get_contents('php://input');
$data = json_decode($input, true);
if ($data['event'] === 'order.status.updated') {
$orderId = $data['orderId'];
$status = $data['status'];
$recipient = $data['recipient'];
$volume = $data['volume'];
// Update your database
// $db->query("UPDATE orders SET status = '$status' WHERE order_id = '$orderId'");
// Send SMS notification
if ($status === 'delivered') {
// send_sms($recipient, "Your {$volume}GB data has been delivered!");
}
}
// Always respond with 200 OK
http_response_code(200);
echo json_encode(['received' => true]);
?>
Important: Your webhook endpoint must respond with HTTP 200 within 5 seconds.
ERROR
Error Responses
Error Response Format
{
"success": false,
"error": "Insufficient wallet balance",
"type": "INSUFFICIENT_BALANCE"
}
Common Error Types
| Error Type | Description | HTTP Status |
|---|---|---|
| UNAUTHORIZED | Invalid or missing API key | 401 |
| INSUFFICIENT_BALANCE | Wallet balance too low | 402 |
| INVALID_OFFER | Invalid offer slug or volume | 400 |
| RATE_LIMIT_EXCEEDED | Too many requests | 429 |
| ORDER_NOT_FOUND | Order ID or reference not found | 404 |