Operators API
Fetch the catalog of mobile operators and the operator_id required to submit a recharge
Operators API
Returns the catalog of mobile operators Starship can recharge, along with what each one supports. You need an operator_id from this endpoint before you can submit a recharge or price one.
Endpoint
GET /api/v1/recharge/operatorsAuthentication: API Key + Secret required
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
country | string | No | IN | ISO-2 country code. v1 is India-only |
A country with no seeded operators returns an empty array, not an error.
Request
curl -X GET "https://api.starshiprewards.com/api/v1/recharge/operators?country=IN" \
-H "X-API-Key: <your-api-key>" \
-H "X-API-Secret: <your-api-secret>"Response
200 OK — a flat array. This endpoint is not paginated: the catalog is a small fixed list.
[
{
"id": 1,
"code": "AIRTEL",
"name": "Airtel",
"logo_url": "https://cdn.example/operators/airtel.png",
"supports_prepaid": true,
"supports_postpaid": true,
"supports_special": false
},
{
"id": 2,
"code": "JIO",
"name": "Jio",
"supports_prepaid": true,
"supports_postpaid": true,
"supports_special": false
}
]Fields
| Field | Type | Description |
|---|---|---|
id | number | Pass this back as operator_id when pricing or submitting |
code | string | Stable machine code, e.g. AIRTEL, JIO, MTNL_DELHI. Safe to match on |
name | string | Display name |
logo_url | string | Operator logo. Omitted entirely when unset — do not assume the key exists |
supports_prepaid | boolean | Prepaid top-ups are available for this operator |
supports_postpaid | boolean | Postpaid bill payments are available for this operator |
supports_special | boolean | "Special" recharges are available. BSNL / MTNL only |
Only active operators are returned. An operator that disappears from this list can no longer be recharged, so refresh your cache rather than pinning ids forever.
supports_* are catalog-level capabilities. Your own account may still be restricted to a subset — a per-client overlay can block an individual operator, and the prepaid/postpaid toggles are set per client. An operator listed here with supports_postpaid: true can still return 403 on submit if postpaid is off for your account.
Caching
This is reference data and is cached for 1 day (with a 10-minute stale-while-revalidate window). Cache it on your side too — fetch it at startup and on a daily refresh, not on every recharge.
Choosing an operator
You must name the operator yourself. Starship does not detect the operator from the mobile number, because Mobile Number Portability means the number series no longer identifies the operator.
Practical approaches:
- Let the user pick. Show
nameandlogo_urlin a dropdown, submit theid. This is the most reliable option. - Map from your own records. If you already store which operator a subscriber is on, map your value to
code(not toname, which is a display string and may be re-worded).
Telecom circles
Some operator/vendor combinations require a circle (telecom region) alongside the operator. Where that applies, circle_id becomes mandatory on submit and omitting it returns a 400.
There is no public circles endpoint in v1. If your integration covers operators that need a circle — BSNL and MTNL are the usual cases — ask your account manager for the circle id list for those operators.
Errors
| Status | Cause |
|---|---|
401 | Missing or invalid API credentials |
500 | Catalog could not be read. Retry with backoff |
Next
Charges API — price a recharge before placing it.