Recharge Operators API

Returns the seeded catalog of mobile operators for a country. You must pass one of these id values as operator_id when quoting or submitting a recharge — Starship never infers the operator from the phone number.

Endpoint

GET /api/v1/recharge/operators

Authentication: API Key + Secret required

Why you have to name the operator

Mobile number portability means a number's prefix no longer identifies its network, and the recharge vendor exposes no lookup that maps a number to its current operator. So the operator is caller-supplied and server-validated: you tell Starship which network to top up, and Starship checks that the operator exists, is active, belongs to the right country, and supports the recharge type you asked for.

Getting it wrong is a rejected recharge, not a misrouted one — POST /api/v1/recharges validates the operator before any money moves.

Request Headers

X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke
X-API-Secret: your-secret-here

Query Parameters

An unseeded country is not an error — it returns an empty array. Since v1 is India-only, any value other than IN returns [].

Response

Success Response

Status Code: 200 OK

Response Headers:

Cache-Control: max-age=86400, stale-while-revalidate=600

Response Body:

[
  {
    "id": 1,
    "code": "AIRTEL",
    "name": "Airtel",
    "logo_url": "https://cdn.starshiprewards.com/operators/airtel.png",
    "supports_prepaid": true,
    "supports_postpaid": true,
    "supports_special": false
  },
  {
    "id": 2,
    "code": "JIO",
    "name": "Jio",
    "supports_prepaid": true,
    "supports_postpaid": false,
    "supports_special": false
  },
  {
    "id": 7,
    "code": "BSNL",
    "name": "BSNL",
    "supports_prepaid": true,
    "supports_postpaid": true,
    "supports_special": true
  }
]

Response Fields

Only active operators for the requested country are returned — you never have to filter the response yourself.

Reading the capability flags

The three flags decide which submit payloads an operator will accept. Submitting a combination the operator does not support is rejected with 400 E_VALIDATION_FAILURE before any money moves.

Prepaid vs postpaid. Prepaid is a top-up — you choose the amount and it is added to the balance. Postpaid is a bill payment — the amount must be one the subscriber actually owes. Most Indian operators support prepaid; postpaid is available on fewer of them.

Special recharge is a distinct vendor product offered only by BSNL and MTNL, and supports_special is true only for those. Leave is_special as false unless you specifically need it — setting it on an operator that does not offer it is rejected.

Caching

Responses carry Cache-Control: max-age=86400, stale-while-revalidate=600 — one day, with a ten-minute stale window. The catalog changes rarely.

Fetch it at startup or on a daily refresh and cache it in your application. Calling it before every recharge spends your general rate-limit budget on data that has not changed.

Errors

This endpoint has no request-specific validation errors — an unknown country returns an empty list, not a 400.

Examples

# Default — India
curl -X GET "{{host}}/api/v1/recharge/operators" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

# Explicit country
curl -X GET "{{host}}/api/v1/recharge/operators?country=IN" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here"

# Operators that accept postpaid bill payment
curl -s -X GET "{{host}}/api/v1/recharge/operators" \
  -H "X-API-Key: sk_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -H "X-API-Secret: your-secret-here" \
  | jq '[.[] | select(.supports_postpaid)] | map({id, code, name})'

Next steps

• Recharge Charges API — quote a price for an operator and amount
• Submit a Recharge — place the recharge