Developer API

Quick Start

Get started with Use Data API in 3 simple steps:

1. Get Your API Key Navigate to your Use Data dashboard → Profile → API tab and copy your unique API key
2. Make Your First Request Use the code examples below to send your first data bundle
3. Monitor Your Usage Track your transactions and wallet balance in real-time

Authentication

Every API request must include your API key in the x-api-key header:

Copyx-api-key: bh_live_your_api_key_here

Base URL

All API endpoints use this base URL:

API Endpoints

All requests are sent as POST with a JSON body specifying the action.

POST Place Order

Purchase and send a data bundle to a recipient.

Request Parameters

Copyconst response = await fetch('https://psmqfcoctovtfrzopcjt.supabase.co/functions/v1/developer-api', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'bh_live_your_api_key_here'
  },
  body: JSON.stringify({
    action: 'place_order',
    network: 'mtn',
    recipient: '0244123456',
    package_size: 5,
    order_id: 'order-12345' // Optional
  })
});

const data = await response.json();
console.log(data);

Copycurl -X POST https://psmqfcoctovtfrzopcjt.supabase.co/functions/v1/developer-api \
  -H "Content-Type: application/json" \
  -H "x-api-key: bh_live_your_api_key_here" \
  -d '{
    "action": "place_order",
    "network": "mtn",
    "recipient": "0244123456",
    "package_size": 5,
    "order_id": "order-12345"
  }'

Copyimport requests

url = "https://psmqfcoctovtfrzopcjt.supabase.co/functions/v1/developer-api"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "bh_live_your_api_key_here"
}
data = {
    "action": "place_order",
    "network": "mtn",
    "recipient": "0244123456",
    "package_size": 5,
    "order_id": "order-12345"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Success Response (200 OK)

Copy{
  "success": true,
  "message": "Order placed successfully",
  "data": {
    "order_id": "API_1702404123_abc",
    "transaction_id": 12345,
    "reference": "SPARK_REF_123",
    "network": "mtn",
    "recipient": "0244123456",
    "package_size": 5,
    "bundle": "5GB",
    "validity": "30 Days",
    "amount": 22.50,
    "status": "processing",
    "new_balance": 477.50,
    "timestamp": "2025-12-12T22:51:00Z"
  }
}

POST Check Balance

Retrieve your current wallet balance.

Request Parameters

Example Request

Copyconst response = await fetch('https://psmqfcoctovtfrzopcjt.supabase.co/functions/v1/developer-api', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'bh_live_your_api_key_here'
  },
  body: JSON.stringify({ action: 'check_balance' })
});

const data = await response.json();
console.log(data);

Success Response

Copy{
  "success": true,
  "data": {
    "wallet_balance": 500.00,
    "currency": "GHS",
    "user": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

POST Get Available Bundles

Fetch all available bundles with your custom pricing applied.

Request Parameters

Example Request

Copyconst response = await fetch('https://psmqfcoctovtfrzopcjt.supabase.co/functions/v1/developer-api', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'bh_live_your_api_key_here'
  },
  body: JSON.stringify({
    action: 'get_bundles',
    network: 'mtn' // Optional filter
  })
});

Success Response

Copy{
  "success": true,
  "data": {
    "bundles": [
      {
        "id": 1,
        "network": "mtn",
        "size": "1GB",
        "size_gb": 1,
        "price": 4.50,
        "validity": "30 Days",
        "has_custom_price": true
      },
      {
        "id": 2,
        "network": "mtn",
        "size": "5GB",
        "size_gb": 5,
        "price": 22.50,
        "validity": "30 Days",
        "has_custom_price": false
      }
    ],
    "count": 2
  }
}

POST Get Transaction History

Retrieve your recent transactions with pagination support.

Request Parameters

Example Request

Copyconst response = await fetch('https://psmqfcoctovtfrzopcjt.supabase.co/functions/v1/developer-api', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'bh_live_your_api_key_here'
  },
  body: JSON.stringify({
    action: 'get_transactions',
    limit: 10,
    offset: 0
  })
});

Success Response

Copy{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": 123,
        "type": "purchase",
        "amount": 22.50,
        "status": "completed",
        "description": "MTN 5GB",
        "created_at": "2025-12-12T22:51:00Z"
      }
    ],
    "count": 1,
    "total": 25
  }
}

Result Checkers & Special Offers

Sell WASSCE/BECE result checkers and special offers through the same API. All requests use the same endpoint and x-api-key header.

get_result_checkers — list checkers, your price & stock

Copy{ "action": "get_result_checkers" }
// → data.result_checkers: [{ type, name, price, available, in_stock }]

buy_result_checker — buy one (returns Serial + PIN)

Copy{ "action": "buy_result_checker", "product_type": "wassce" }
// → data: { name, serial, pin, amount, wallet_balance }

get_special_offers — list active offers & your price

Copy{ "action": "get_special_offers" }
// → data.special_offers: [{ id, title, description, price }]

buy_special_offer — buy an offer for a customer

Copy{ "action": "buy_special_offer", "offer_id": 3, "recipient": "0241234567" }
// → data: { order_id, amount, status: "processing", new_balance }

Share Bundles (iShare & Telecel)

Send data to any recipient from your pre-loaded share balance. iShare is denominated in MB (AirtelTigo); Telecel Share is denominated in GB. These draw from your share balance — not your wallet. Top up your share balance with the admin. Same endpoint and x-api-key header as every other call.

get_ishare_balance / get_telecel_balance — check share balance

Copy{ "action": "get_ishare_balance" }
// → data: { network: "iShare", balance: 5000, unit: "MB", enabled: true }

{ "action": "get_telecel_balance" }
// → data: { network: "Telecel", balance: 20, unit: "GB", enabled: true }

share_ishare — send iShare data (MB)

Copy{ "action": "share_ishare", "recipient": "0271234567", "mb": 1000 }
// optional: "order_id" for idempotency
// → data: { order_id, recipient, amount: 1000, unit: "MB", status: "processing", balance_remaining }

share_telecel — send Telecel data (GB)

Copy{ "action": "share_telecel", "recipient": "0201234567", "gb": 2.5 }
// optional: "order_id" for idempotency
// → data: { order_id, recipient, amount: 2.5, unit: "GB", status: "processing", balance_remaining }

If the provider rejects the order your share balance is automatically refunded and the call returns success: false. Reusing an order_id returns the original order without charging twice.

Error Handling

All errors return JSON with success: false and descriptive error messages.

401 Unauthorized - Invalid API Key

Copy{
  "success": false,
  "error": "Invalid API key",
  "message": "Authentication failed. Please provide a valid API key.",
  "code": 401
}

400 Bad Request - Insufficient Balance

Copy{
  "success": false,
  "error": "Insufficient balance",
  "message": "Required: GH₵ 22.50, Available: GH₵ 10.00"
}

400 Bad Request - Invalid Phone Number

Copy{
  "success": false,
  "error": "Invalid phone number",
  "message": "Phone number must be 10 digits starting with 0 (e.g., 0241234567)"
}

400 Bad Request - Bundle Not Found

Copy{
  "success": false,
  "error": "Bundle not found",
  "message": "No active bundle found for mtn with size 999GB"
}

Best Practices

Need Help?

If you encounter any issues or have questions:

• Verify your API key is correct and starts with bh_live_
• Ensure your wallet has sufficient balance
• Check phone numbers are 10 digits starting with 0
• Review error messages for specific details
• Contact support through your Use Data dashboard