Catalog Lookup

Look up the available airtime products for a phone number or network. The API automatically detects the phone's network via HLR lookup, or you can specify a network_id manually for ported numbers. You can also use network_id alone without a phone number to browse products for a known network.

GET /v2/catalog/lookup

Permission required: airtime.read

Query Parameters

Example Request

curl -X GET "https://api.clickairtime.com/v2/catalog/lookup?phone_number=%2B233541112259" \
  -H "Authorization: Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const response = await fetch(
  'https://api.clickairtime.com/v2/catalog/lookup?phone_number=%2B233541112259',
  {
    headers: {
      'Authorization': 'Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    },
  }
);
const data = await response.json();

import requests

response = requests.get(
    'https://api.clickairtime.com/v2/catalog/lookup',
    params={'phone_number': '+233541112259'},
    headers={
        'Authorization': 'Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    }
)
data = response.json()

$ch = curl_init('https://api.clickairtime.com/v2/catalog/lookup?phone_number=%2B233541112259');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ce_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch));

Example Response

{
  "success": true,
  "data": {
    "phone_number": "+233541112259",
    "network": {
      "id": 42,
      "name": "MTN Ghana",
      "country": "Ghana",
      "country_code": "GH",
      "currency": "GHS"
    },
    "exchange_rate": {
      "source_currency": "USD",
      "destination_currency": "GHS",
      "rate": 12.35
    },
    "products": {
      "custom_airtime": {
        "available": true,
        "min_amount_local": 1,
        "max_amount_local": 5000,
        "local_currency": "GHS"
      },
      "fixed_bundles": [
        {
          "id": 101,
          "name": "500MB Data - 30 Days",
          "type": "DATA",
          "price_usd": 2.50,
          "local_value": "500MB Data - 30 Days",
          "local_currency": "GHS",
          "description": "500MB Data - 30 Days"
        },
        {
          "id": 102,
          "name": "1GB Data - 30 Days",
          "type": "DATA",
          "price_usd": 4.00,
          "local_value": "1GB Data - 30 Days",
          "local_currency": "GHS",
          "description": "1GB Data - 30 Days"
        }
      ]
    },
    "sms_notification": {
      "available": true,
      "cost_usd": 0.10
    }
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Response Fields