API Documentation — GhanaDataHub

📖 Introduction

The GhanaDataHub API lets you build reseller apps, automate data purchases, or integrate data bundles into existing platforms. All endpoints return JSON and require an API key.

🚀 Quick Start (4 Steps)

1

Create a free account

Register at ghanadatahub.net/register — takes under 2 minutes.

2

Fund your wallet

Add credit to your main wallet from the dashboard using Paystack (VISA, MasterCard, MoMo).

3

Generate your API key

Go to Profile → API Keys and generate a key. Keep it secret.

4

Make your first request

Use the examples below to test your key and start purchasing bundles programmatically.

cURL — Quick Test

# Check your wallet balance to verify your API key
curl https://ghanadatahub.net/api/v1/balance \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

🔑 Authentication

All API requests require your API key in the x-api-key header. Never expose your key in frontend or client-side code.

⚠️

Keep your API key secret. Treat it like a password. If compromised, regenerate it immediately from your dashboard.

Required Headers

Header	Value	Description
x-api-key	string	Your API key — find it under Profile → API Keys
Accept	string	Must be `application/json`
Content-Type	string	Required for POST requests: `application/json`

Example Request Headers

x-api-key:       ghd_live_xxxxxxxxxxxxxxxxxxxxxxxx
Accept:          application/json
Content-Type:    application/json

GET Check Balance

Returns your current wallet balances — main, referral and agent.

GET/api/v1/balanceNo body required

cURL

curl https://ghanadatahub.net/api/v1/balance \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

● 200 OK

Response

{
  "success": true,
  "balance": { "main": 150.00, "referral": 12.50, "agent": 30.00 },
  "currency": "GHS"
}

GET Get Networks

Returns all active networks available for data purchases. Use the network id to fetch bundles.

GET/api/v1/networks

cURL

curl https://ghanadatahub.net/api/v1/networks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

● 200 OK

Response

{
  "success": true,
  "networks": [
    { "id": 1, "name": "MTN", "slug": "mtn", "color": "#FFC300", "delivery": "5-60 minutes", "bundles_count": 10 },
    { "id": 2, "name": "Telecel", "slug": "telecel", "color": "#E40032", "delivery": "5-60 minutes", "bundles_count": 6 },
    { "id": 3, "name": "AirtelTigo (iShare)", "slug": "airteltigo", "color": "#E40000", "delivery": "Instant", "bundles_count": 10 }
  ]
}

GET Get Bundles

Returns all active bundles for a specific network. Prices shown reflect your account's price group.

GET/api/v1/networks/{network_id}/bundles

Path Parameters

Parameter	Type	Required	Description
network_id	integer	Required	Network ID from /networks (e.g. 1 = MTN)

cURL — MTN Bundles

curl https://ghanadatahub.net/api/v1/networks/1/bundles \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

● 200 OK

Response

{
  "success": true, "network": "MTN",
  "bundles": [
    { "id": 10, "name": "1GB Data Bundle", "size": "1GB", "price": 5.39, "badge": "Non-Expiry", "is_active": true },
    { "id": 11, "name": "2GB Data Bundle", "size": "2GB", "price": 10.78, "badge": "Non-Expiry", "is_active": true }
  ]
}

POST Place Order

Purchase a data bundle for a Ghana phone number. The bundle price is deducted from your main wallet balance instantly.

⚠️

Double-check the phone number. Data is delivered immediately and there are no refunds for wrong numbers.

POST/api/v1/orders

Request Body (JSON)

Parameter	Type	Required	Description
bundle_id	integer	Required	Bundle ID from /networks/{id}/bundles
phone_number	string	Required	Ghana number — `0XXXXXXXXX` or `233XXXXXXXXX`
reference	string	Optional	Your own reference for tracking (max 100 chars)

cURL

curl https://ghanadatahub.net/api/v1/orders \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"bundle_id":10,"phone_number":"0244123456","reference":"MY-REF-001"}'

PHP (cURL)

$ch = curl_init('https://ghanadatahub.net/api/v1/orders');
curl_setopt_array($ch, [
  CURLOPT_POST=>true, CURLOPT_RETURNTRANSFER=>true,
  CURLOPT_HTTPHEADER=>['x-api-key: YOUR_API_KEY','Content-Type: application/json','Accept: application/json'],
  CURLOPT_POSTFIELDS=>json_encode(['bundle_id'=>10,'phone_number'=>'0244123456','reference'=>'MY-REF-001']),
]);
$res = json_decode(curl_exec($ch), true); curl_close($ch);

● 200 OK — Success

Response — Success

{
  "success": true, "message": "1GB data sent to 0244123456 successfully",
  "order": { "order_number": "ORD-XXXXXXXXXXX", "bundle": "MTN 1GB", "phone_number": "0244123456", "amount_paid": 5.39, "status": "successful" },
  "wallet_balance": 144.61
}

● 400 — Insufficient Balance

Response — Error

{ "success": false, "message": "Insufficient wallet balance", "balance": 2.50, "required": 5.39 }

GET Order Status

Check the real-time status of an order by its order number.

GET/api/v1/orders/{order_number}

cURL

curl https://ghanadatahub.net/api/v1/orders/ORD-XXXXXXXXXXX \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

● 200 OK

Response

{
  "success": true,
  "order": { "order_number": "ORD-XXXXXXXXXXX", "bundle": "MTN 1GB", "network": "MTN", "phone_number": "0244123456", "amount_paid": 5.39, "status": "successful", "created_at": "2026-10-07T10:00:00Z" }
}

ℹ️

Order Statuses: pending — processing · successful — delivered · failed — failed (wallet refunded)

GET Order History

Returns a paginated list of your orders, newest first. Filter by status or network.

GET/api/v1/orders

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number (default: 1)
per_page	integer	Optional	Items per page — max 50, default 20
status	string	Optional	Filter: `pending`, `successful`, `failed`

cURL — Successful Orders

curl "https://ghanadatahub.net/api/v1/orders?status=successful&page=1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

GET Profile

Returns your account details and current plan information.

GET/api/v1/profile

cURL

curl https://ghanadatahub.net/api/v1/profile \
  -H "x-api-key: YOUR_API_KEY"

● 200 OK

Response

{
  "success": true,
  "user": { "name": "Kwame Mensah", "email": "kwame@example.com", "username": "kwame123", "price_group": "Standard", "role": "user" }
}

⚠️ Error Codes

All error responses return JSON with success: false and a descriptive message.

Code	Status	Description
200	OK	Request succeeded
400	Bad Request	Invalid parameters, insufficient balance, or bundle unavailable
401	Unauthorized	Missing or invalid API key in `x-api-key` header
404	Not Found	Order, network or bundle not found
422	Validation Error	Request body failed validation — check the `errors` field
429	Rate Limited	Too many requests — retry after 60 seconds
500	Server Error	Internal error — contact support if it persists

🚦 Rate Limits

Requests are rate-limited per API key to prevent abuse. Exceeding limits returns a 429 response.

Endpoint	Limit	Window
All endpoints	60 requests	Per minute
POST /orders	10 orders	Per minute
GET /balance	30 requests	Per minute

💡

Tip: Cache the /networks and /bundles responses locally for 30 minutes — they rarely change and don't count toward your order limits.

🪝 Webhooks Coming Soon

Webhooks will POST to your URL when order status changes — no more polling needed.

When webhooks launch, you'll set your endpoint URL in your dashboard. We'll notify you when:
• Order status → successful (data delivered)
• Order status → failed (wallet refunded)
• Wallet funded or debited

📦 Full Integration Example

A complete example showing how to list bundles and place an order in PHP and Python.

PHP — Full Purchase Flow

PHP

$apiKey  = 'YOUR_API_KEY';
$baseUrl = 'https://ghanadatahub.net/api/v1';
function ghd($method, $path, $body = null) {
  global $apiKey, $baseUrl;
  $ch = curl_init($baseUrl . $path);
  curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST=>$method,CURLOPT_RETURNTRANSFER=>true,CURLOPT_HTTPHEADER=>['x-api-key: '.$apiKey,'Content-Type: application/json','Accept: application/json'],CURLOPT_POSTFIELDS=>$body?json_encode($body):null]);
  $res = json_decode(curl_exec($ch), true); curl_close($ch); return $res;
}
$bal     = ghd('GET',  '/balance');
$bundles = ghd('GET',  '/networks/1/bundles');
$order   = ghd('POST', '/orders', ['bundle_id'=>10,'phone_number'=>'0244123456']);
echo $order['message'];

Python — Full Purchase Flow

Python

import requests
API_KEY  = 'YOUR_API_KEY'
BASE_URL = 'https://ghanadatahub.net/api/v1'
HEADERS  = {'x-api-key': API_KEY, 'Accept': 'application/json'}
bal     = requests.get(f'{BASE_URL}/balance', headers=HEADERS).json()
bundles = requests.get(f'{BASE_URL}/networks/1/bundles', headers=HEADERS).json()
order   = requests.post(f'{BASE_URL}/orders', headers={**HEADERS,'Content-Type':'application/json'}, json={'bundle_id':10,'phone_number':'0244123456'}).json()
print(order['message'])