API Documentation

Basics

Base URL: https://planwala.goter.in/api/v1

Har request me header bhejo: X-API-Key: YOUR_API_KEY (ya ?api_key= query param).

Charge sirf successful /plans, /dth-plans aur /lookup response (HTTP 200) par lagta hai. Error, no-data, operators/circles/balance — free.

Rate limit: 120 requests/minute per key. Best practice: plans apne server par 6–12 ghante cache karo.

GET /plans — Mobile prepaid plans

ParamRequiredExample
operatorYesairtel, jio, vi, bsnl
circleYesWB, DL, MU …
categoryNoUnlimited, Data, Talktime …
curl "https://planwala.goter.in/api/v1/plans?operator=airtel&circle=WB" -H "X-API-Key: YOUR_API_KEY"
{
  "status": "success",
  "operator": "Airtel",
  "circle": "West Bengal",
  "updated": "2026-11-04 03:00:00",
  "count": 2,
  "plans": {
    "Unlimited": [
      { "id": 11, "amount": 349, "validity": "28 days", "data": "2GB/day",
        "calls": "Unlimited", "sms": "100/day", "description": "..." }
    ],
    "Data": [ { "id": 15, "amount": 19, "validity": "1 day", "data": "1GB", ... } ]
  },
  "charged": 0.1,
  "balance": 99.9,
  "time_ms": 12
}

GET /dth-plans — DTH plans

curl "https://planwala.goter.in/api/v1/dth-plans?operator=tataplay" -H "X-API-Key: YOUR_API_KEY"

GET /lookup — Number se operator + circle

Mobile number port (MNP) hone ke baad wala asli operator aur circle batata hai. Charge: ₹0.25 per successful lookup.
Jald aa raha hai — abhi ye endpoint 503 deta hai (charge nahi).

ParamRequiredExample
numberYes98XXXXXXXX (10 digit; +91 / 0 bhi chalega)
curl "https://planwala.goter.in/api/v1/lookup?number=98XXXXXXXX" -H "X-API-Key: YOUR_API_KEY"
{
  "status": "success",
  "number": "98XXXXXX12",
  "operator": { "code": "jio", "name": "Jio" },
  "circle": { "code": "WB", "name": "West Bengal" },
  "ported": true,
  "checked_at": "2026-11-05 10:20:00",
  "cached": false,
  "charged": 0.25,
  "balance": 99.75
}

Agla step: operator.code aur circle.code seedha /plans me bhejo. Agar operator.code null ho (jaise MTNL), to name me provider ka naam milega. User ko operator badalne ka option zaroor do — koi bhi lookup 100% nahi hota.

GET /operators · GET /circles · GET /balance

curl "https://planwala.goter.in/api/v1/operators" -H "X-API-Key: YOUR_API_KEY"
curl "https://planwala.goter.in/api/v1/balance"   -H "X-API-Key: YOUR_API_KEY"

PHP example

$ch = curl_init("https://planwala.goter.in/api/v1/plans?operator=jio&circle=WB");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: YOUR_API_KEY"],
  CURLOPT_TIMEOUT => 10,
]);
$res = json_decode(curl_exec($ch), true);
if ($res['status'] === 'success') {
  foreach ($res['plans'] as $category => $plans) {
    foreach ($plans as $p) echo "$category: ₹{$p['amount']} - {$p['validity']} - {$p['data']}\n";
  }
}

JavaScript, Android (OkHttp/Retrofit), Flutter — sab me same URL aur X-API-Key header. Mobile app me key mat rakho: app → aapka server → PlanWala API.

Error codes

HTTPMatlab
400Galat operator/circle ya mobile number
401API key missing ya galat
402Wallet balance kam hai
403Account suspended
404Is operator/circle ka data abhi nahi (charge nahi)
429Rate limit cross
503Number lookup abhi available nahi (charge nahi)

Codes

Operators
airtelAirtel (mobile)
bsnlBSNL (mobile)
jioJio (mobile)
viVi (Vodafone Idea) (mobile)
airteldthAirtel Digital TV (dth)
d2hd2h (dth)
dishtvDish TV (dth)
sundirectSun Direct (dth)
tataplayTata Play (dth)
Circles
APAndhra Pradesh & Telangana
ASAssam
BRBihar & Jharkhand
CHChennai
DLDelhi NCR
GJGujarat
HRHaryana
HPHimachal Pradesh
JKJammu & Kashmir
KAKarnataka
KLKerala
KOKolkata
MPMadhya Pradesh & Chhattisgarh
MHMaharashtra & Goa
MUMumbai
NENorth East
OROdisha
PBPunjab
RJRajasthan
TNTamil Nadu
UEUP East
UWUP West
WBWest Bengal