API Documentation – Mitra Plans

Contents

Authentication Request signing (optional)Response format & errors Rate limits GET /status GET /operators GET /circles GET /categories GET /detect GET /detect/report (MNP feedback) GET /plans/mobile GET /plans/dth GET /dth/operator GET /dth/info GET /plans/search GET /plan/{id}GET /usage Code samples

Partner API v1

Base URL: https://plans.mitrait.in/api/partner/v1. All endpoints are GET and return JSON (UTF-8). Data covers 4 mobile operators (Reliance Jio, Airtel, Vi (Vodafone Idea), BSNL), 5 DTH operators and 23 circles, refreshed automatically.

Authentication

Send your credentials on every request as HTTP headers:

X-Api-Key: YOUR_API_KEY X-Api-Secret: YOUR_API_SECRET

Query parameters api_key / api_secret are accepted as a fallback but headers are strongly recommended. Always call the API from your server – never embed the secret in mobile apps or browser JavaScript.

Request signing (optional, recommended)

Instead of sending the secret, sign each request. Enable "Require signed requests" under Security to enforce it.

X-Api-Key: YOUR_API_KEY X-Timestamp: 1735689600 (unix seconds, ±5 min) X-Signature: hex( HMAC_SHA256( secret, timestamp + "\n" + path ) ) path = the endpoint path starting at /api/partner/v1, without query string, e.g. /api/partner/v1/plans/mobile (do NOT include any installation sub-folder)

Response format

{"success": true, "data": [...], "meta": {"request_id": "…", "timestamp": "…", "count": 42}}

Errors use a non-200 status and:

{"success": false, "error": {"code": "RATE_LIMIT_MINUTE", "message": "Rate limit of 60 requests/minute exceeded."}}

HTTP	Code	Meaning
401	AUTH_MISSING / AUTH_INVALID / AUTH_SIGNATURE	Missing or wrong credentials / signature
403	ACCOUNT_PENDING / ACCOUNT_SUSPENDED / API_BLOCKED / API_PAUSED	Account not active
403	IP_NOT_ALLOWED	Caller IP not in whitelist / in blacklist
403	ENDPOINT_FORBIDDEN / TYPE_FORBIDDEN / OPERATOR_FORBIDDEN	Your permissions do not include this resource
422	INVALID_OPERATOR / INVALID_CIRCLE / INVALID_MOBILE / INVALID_QUERY	Bad parameter
404	NOT_FOUND	Plan does not exist or is inactive
429	RATE_LIMIT_MINUTE / RATE_LIMIT_DAILY / RATE_LIMIT_MONTHLY	Quota exceeded – see headers

Rate limits

Your limits are shown on the dashboard. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-Daily-Remaining and X-Monthly-Remaining. Cache plan lists on your side for 5–15 minutes; plans change at most a few times per day.

GET/status

Connectivity check, your permissions, quota usage and data freshness.

https://plans.mitrait.in/api/partner/v1/status

GET/operators?type=mobile|dth

List of operators you may query. Use the code value in plan requests.

https://plans.mitrait.in/api/partner/v1/operators?type=mobile

{"success":true,"data":[{"id":1,"code":"jio","name":"Reliance Jio","short_name":"Jio","type":"mobile","color":"#0a2885","last_updated":"2026-08-23 19:22:40"}, …],"meta":{"type":"mobile","count":5}}

GET/circles

All telecom circles with the states they cover. Use code in mobile plan requests.

https://plans.mitrait.in/api/partner/v1/circles

{"success":true,"data":[{"id":5,"code":"DL","name":"Delhi NCR","states":["Delhi","Noida","Gurgaon","Ghaziabad","Faridabad"]}, …]}

GET/categories?type=mobile|dth

Plan categories (slug used for the category filter).

https://plans.mitrait.in/api/partner/v1/categories?type=mobile

GET/detect?mobile=98XXXXXXXX

Detect the operator and circle of a mobile number using our local numbering-series database (no third-party lookup). MNP limitation: the result reflects the operator to which the number series was allocated; a number ported to another operator will still return the allocation operator, so always let your users change the operator manually. operator is null when no series matches.

https://plans.mitrait.in/api/partner/v1/detect?mobile=9810012345

{"success":true,"data":{"mobile":"9810012345","operator":{"id":2,"code":"airtel","name":"Airtel"},"circle":{"id":5,"code":"DL","name":"Delhi NCR"},"source":"prefix","confidence":"medium","prefix":"9810","mnp_note":"Detected from the number series allocation. If this number was ported (MNP) to another operator, please select the operator manually."}}

GET/detect/report?mobile=…&operator=…[&circle=…]&source=recharge|user

Help beat MNP. After a successful recharge (source=recharge) or when your user corrects the auto-selected operator (source=user), report it. The number is stored hashed with its real operator, so the next /detect for that number returns the current operator with confidence: high and ported: true/false – at no cost.

https://plans.mitrait.in/api/partner/v1/detect/report?mobile=9876543210&operator=jio&circle=PB&source=recharge

Also: add &mnp=1 to /detect to request an external MNP/HLR lookup when the platform has one configured (subject to the platform policy). Detect responses include ported (true / false / null = unknown) and mnp_checked.

GET/plans/mobile

`operator` *	operator code, e.g. `jio`
`circle` *	circle code, e.g. `DL`
`category`	slug: all (default), popular, unlimited, data, 5g, talktime, sms, ott, roaming, annual, other
`q`	keyword filter, e.g. `2gb`, `netflix`, `84`
`min_price`, `max_price`	price range in ₹
`sort`	price_asc (default), price_desc, validity_desc, validity_asc

https://plans.mitrait.in/api/partner/v1/plans/mobile?operator=jio&circle=DL&category=unlimited

{"success":true,"data":[{"id":124,"name":null,"price":299,"validity":"28 Days","validity_days":28,"data_benefit":"2GB/day","talktime":"Unlimited Calls","sms":"100 SMS/day","ott":null,"channels":null,"description":"Unlimited Voice | 2GB/Day Data | 100 SMS/Day | Unlimited 5G | Jio Apps","benefits":["Unlimited Voice","2GB/Day Data","100 SMS/Day","Unlimited 5G","Jio Apps"],"is_featured":false,"updated_at":"2026-08-23 19:22:40","category":"unlimited","category_name":"Unlimited"}, …], "meta":{"type":"mobile","operator":{"id":1,"code":"jio","name":"Reliance Jio"},"circle":{"id":5,"code":"DL","name":"Delhi NCR"},"count":12,"total":30,"category_counts":{"unlimited":12,"data":7,…},"last_updated":"2026-08-23 19:22:40"}}

GET/plans/dth

`operator` *	DTH operator code, e.g. `tataplay`
`category`	all, monthly, quarterly, half-yearly, annual, hd, sd, addon, regional, other
`q`, `min_price`, `max_price`, `sort`	as above

https://plans.mitrait.in/api/partner/v1/plans/dth?operator=tataplay&category=hd

GET/dth/operator?dth_number=…

Identify the DTH operator from a customer ID / VC number (9–13 digits). Requires the dth_operator permission. Results are cached, so repeat lookups are free and fast.

https://plans.mitrait.in/api/partner/v1/dth/operator?dth_number=70512345661

{"success":true,"data":{"dth_number":"70512345661","operator":{"id":10,"code":"sundirect","name":"Sun Direct"},"source":"way2api"}}

GET/dth/info?dth_number=…&operator=tataplay|airteldth|dishtv|d2h|sundirect|auto

Customer profile behind a DTH ID: name, registered mobile, balance, monthly amount, status, plan, next/last recharge, switch-off date and address. Use operator=auto (or omit it) to detect the operator first. Requires the dth_info permission. Responses are cached for a few minutes; add &fresh=1 to force a live lookup. Fields the operator does not publish are null.

https://plans.mitrait.in/api/partner/v1/dth/info?dth_number=01234567890&operator=dishtv

{"success":true,"data":{"dth_number":"01234567890","operator":"dishtv","operator_name":"Dish TV","customer_id":"9700000123","name":"Lakshmi Priya","registered_mobile":"98XXXXXX10","balance":194.73,"monthly_amount":null,"status":"Active","plan":null,"next_recharge_date":"2026-08-04","last_recharge_date":null,"last_recharge_amount":null,"switch_off_date":"2026-08-07","address":"12 MAIN ROAD, VILLIANUR, PONDICHERRY, Pin - 605110","city":"PONDICHERRY","district":null,"state":"PONDICHERRY","pin_code":"605110"},"meta":{"operator":{"code":"dishtv","name":"Dish TV"},"source":"way2api","fetched_at":"2026-08-23 22:10:00"}}

Errors: INVALID_DTH_NUMBER (422), NO_RECORD_FOUND / REQUEST_FAILED (404 – ID not valid for that operator), OPERATOR_NOT_DETECTED (404), SERVICE_UNAVAILABLE (503).

GET/plans/search?type=mobile|dth&q=…

Search across all operators and circles by price or keyword (max 100 results).

https://plans.mitrait.in/api/partner/v1/plans/search?type=mobile&q=299

GET/plan/{id}

Full details of one plan.

https://plans.mitrait.in/api/partner/v1/plan/124

GET/usage

Your own usage summary, daily series and per-endpoint breakdown (last 30 days).

https://plans.mitrait.in/api/partner/v1/usage

Code samples

PHP (cURL)

$ch = curl_init('https://plans.mitrait.in/api/partner/v1/plans/mobile?operator=jio&circle=DL'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-Api-Key: YOUR_API_KEY', 'X-Api-Secret: YOUR_SECRET'], ]); $res = json_decode(curl_exec($ch), true); foreach ($res['data'] as $plan) { echo $plan['price'], ' - ', $plan['validity'], ' - ', $plan['description'], PHP_EOL; }

PHP – signed request

$path = '/api/partner/v1/plans/mobile'; // always starts at /api/partner/v1 (no sub-folder) $ts = time(); $sig = hash_hmac('sha256', $ts . "\n" . $path, 'YOUR_SECRET'); // headers: X-Api-Key, X-Timestamp: $ts, X-Signature: $sig

JavaScript (Node.js)

const res = await fetch('https://plans.mitrait.in/api/partner/v1/plans/dth?operator=tataplay', { headers: { 'X-Api-Key': 'YOUR_API_KEY', 'X-Api-Secret': process.env.PLANS_SECRET } }); const { success, data, meta } = await res.json();

Python

import requests r = requests.get('https://plans.mitrait.in/api/partner/v1/detect', params={'mobile': '9810012345'}, headers={'X-Api-Key': 'YOUR_API_KEY', 'X-Api-Secret': 'YOUR_SECRET'}) print(r.json()['data'])