{ "openapi": "3.1.0", "info": { "title": "API Sathi", "version": "1.0.0", "description": "One API, every vendor. INR-priced KYC, OCR and communication APIs routed to the cheapest healthy upstream." }, "servers": [ { "url": "https://apisathi.in/gw/v1" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your live or test key, e.g. `live_xxxxxxxxxxxx`." } } }, "tags": [ { "name": "kyc", "description": "KYC & verification products" }, { "name": "ocr", "description": "OCR & document extraction" }, { "name": "communication", "description": "SMS & WhatsApp messaging" } ], "paths": { "/bank-statement-analyse-v1": { "post": { "operationId": "bankStatementAnalyseV1", "tags": [ "ai" ], "summary": "Bank Statement Analyser", "description": "AI-powered bank statement analysis. Upload a digital bank-statement PDF (base64) and get parsed transactions, income & EMI detection, monthly summaries, category breakdown, FOIR, and a fraud/tamper check. Works across banks without per-bank templates.\n\nSYNC (default): POST returns the full analysis (allow up to ~180s for large 6–12 month statements). ASYNC (recommended for large statements): set \"async\": true (or pass a \"callback_url\") — POST returns 202 { job_id } immediately, then either poll GET /v1/bank-statement-analyse-v1/result/{job_id} (200 = done, 202 = still processing, 422 = failed) or receive the result at your callback_url (POST, signed with HMAC-SHA256 in the X-Signature header when configured). Billing: you are charged once per successful analysis; failed statements (422) are not charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pdf_base64" ], "properties": { "pdf_base64": { "type": "string", "description": "Base64-encoded bank-statement PDF (digital/native, not a scan). Max 15MB." }, "password": { "type": "string", "description": "PDF password, if the statement is locked." }, "async": { "type": "boolean", "description": "If true, returns 202 { job_id } immediately; fetch the result by polling or callback." }, "callback_url": { "type": "string", "description": "Optional. If set, the analysis is processed async and POSTed here when ready (implies async)." } }, "additionalProperties": false }, "example": { "pdf_base64": "", "password": "optional-pdf-password" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "description": "Holder, masked account no., bank, IFSC." }, "period": { "type": "object" }, "summary": { "type": "object", "description": "Totals, transaction count, avg/min/max balance." }, "income": { "type": "object", "description": "Estimated monthly income + salary credits." }, "obligations": { "type": "object", "description": "Estimated monthly EMI + loan debits." }, "bounces": { "type": "object", "description": "Count + list of returned/bounced entries." }, "risk": { "type": "object", "description": "FOIR + tamper check (running-balance reconciliation, PDF fingerprint)." }, "monthly": { "type": "array", "description": "Per-month credits, debits, avg balance, salary, EMI." } }, "additionalProperties": true }, "example": { "account": { "account_holder": "RAHUL VERMA", "account_number": "XXXXXX4321", "bank": "HDFC Bank", "ifsc": "HDFC0001234" }, "period": { "from": "2026-04-01", "to": "2026-06-30", "months": 3 }, "summary": { "total_credits": 240000, "total_debits": 88000, "transaction_count": 16, "avg_monthly_balance": 61250.5 }, "income": { "estimated_monthly_income": 80000, "salary_credit_count": 3 }, "obligations": { "estimated_monthly_emi": 15000, "emi_debit_count": 3 }, "bounces": { "count": 1 }, "risk": { "foir": 0.1875, "tamper": { "is_suspicious": false, "score": 0, "checks": [] } }, "monthly": [ { "month": "2026-04", "credits": 80000, "debits": 29300, "salary_credited": 80000 } ] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/estamp-articles-v1": { "post": { "operationId": "estampArticlesV1", "tags": [ "esign" ], "summary": "e-Stamp — Article Catalogue", "description": "List the stamp articles available for a state, with the `articleId` you must quote when creating an order.\n\nCall this FIRST. An article is the head of charge under the state Stamp Act (Simple Agreement, Affidavit, Works Contract, Power of Attorney, and so on), and `articleId` values are state-specific — an id valid in Rajasthan is not valid in Maharashtra. Creating an order with a mismatched article is rejected.\n\nThe full catalogue is large (1600+ rows across states); filter client-side on `stateCode` for the state you are stamping in. Reference lookup, priced at a nominal rate.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "articles": { "type": "array", "description": "Every article across all states: { id, number, description, stateCode, purposes[] }. Filter by stateCode." } }, "additionalProperties": true }, "example": { "articles": [ { "id": 2641, "number": "Article 4", "description": "Affidavit", "stateCode": "HR", "purposes": [] }, { "id": 3312, "number": "Article 5(g)", "description": "Simple Agreement", "stateCode": "RJ", "purposes": [] } ] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/estamp-create-v1": { "post": { "operationId": "estampCreateV1", "tags": [ "esign" ], "summary": "e-Stamp — Create Order", "description": "Create an electronic stamp-paper order. Returns an `order_id` you then poll with estamp-status-v1 for the stamped document.\n\nBILLING — read this before integrating. Two separate amounts are charged for one call:\n1. A flat service fee per order (the price shown for this product).\n2. The STAMP DUTY itself, which is passed through to the state at cost — the total of every `stampDutyAmount` in `series`.\nFor a Rajasthan stamp (`stateCode: \"RJ\"`) the state levies a 30% surcharge on the duty, which is added automatically. The surcharge follows the STAMP, not your billing address: a Maharashtra-registered company stamping in Rajasthan pays it.\n\nSo a Rajasthan order with 5000 duty is charged: service fee + 6500 duty. Make sure your wallet covers both, or the call returns 402 INSUFFICIENT_BALANCE before anything is created.\n\n`refId` must be unique per order (use your loan account number or similar) — a repeat is rejected, which makes retries safe. `articleId` comes from estamp-articles-v1 and must be valid for your `stateCode`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stateCode", "firstPartyName", "secondPartyName", "stampDutyPaidBy", "refId", "series" ], "properties": { "stateCode": { "type": "string", "description": "Two-letter state code the stamp is issued under, e.g. \"RJ\". Drives both the valid articleIds and the 30% Rajasthan surcharge." }, "firstPartyName": { "type": "string", "description": "First party to the instrument." }, "secondPartyName": { "type": "string", "description": "Second party to the instrument." }, "stampDutyPaidBy": { "type": "string", "description": "Which party bears the duty — normally the first party." }, "refId": { "type": "string", "description": "Your unique reference (e.g. loan account no.). Must be unique per order — a repeat is rejected, so retries are safe." }, "series": { "type": "array", "description": "One entry per stamp. stampDutyAmount is in RUPEES and is passed through to the state at cost.", "items": { "type": "object", "required": [ "stampDutyAmount", "stampType", "articleId", "purpose", "considerationPrice" ], "properties": { "stampDutyAmount": { "type": "number", "description": "Duty in rupees for this stamp." }, "stampType": { "type": "string", "enum": [ "ESTAMP" ] }, "articleId": { "type": "number", "description": "From estamp-articles-v1, valid for your stateCode." }, "purpose": { "type": "string", "minLength": 1, "maxLength": 150 }, "considerationPrice": { "type": "number", "description": "Value of the underlying transaction, in rupees." } } } } } }, "example": { "stateCode": "RJ", "firstPartyName": "Pravaha Infinity Private Limited", "secondPartyName": "Rahul Verma", "stampDutyPaidBy": "Pravaha Infinity Private Limited", "refId": "LOAN-2026-000123", "series": [ { "stampDutyAmount": 500, "stampType": "ESTAMP", "articleId": 3312, "purpose": "Loan agreement", "considerationPrice": 250000 } ] } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Poll this with estamp-status-v1 to collect the stamped document." }, "message": { "type": "string" } }, "additionalProperties": true }, "example": { "order_id": "SPRAV000001", "message": "Order created successfully." } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/estamp-status-v1": { "post": { "operationId": "estampStatusV1", "tags": [ "esign" ], "summary": "e-Stamp — Order Status", "description": "Fetch the current status of an order created with estamp-create-v1, and the stamped certificate once it is issued.\n\nWHERE THE CERTIFICATE IS. When `data.status` is FULFILLED (or CONSUMED), the certificate PDF link is `data.stampCertificateUrl` and its id is `data.eStampId`. Each stamp is also listed in `data.orderItems[]` with its own `certificateNo`, `eStampId` and `stampCertificateUrl`. There is no separate documents array. The top-level `status` is only a message; the order status is `data.status`.\n\nTHE LINK EXPIRES. `stampCertificateUrl` is a time-limited link: download the PDF and store it in your own system as soon as the order is FULFILLED. To get a fresh link later, call this API again.\n\nTEST MODE returns a FULFILLED order whose link opens a sample certificate marked SAMPLE - NOT VALID, so you can build and test the download step.\n\nStamping is not instant: poll every few seconds (not in a tight loop) while `data.status` is IN_PROGRESS. Priced at a nominal rate so polling is cheap.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order_id" ], "properties": { "order_id": { "type": "string", "description": "The order_id returned by estamp-create-v1." } }, "additionalProperties": false }, "example": { "order_id": "SPRAV000001" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "A human-readable message. The ORDER status is data.status." }, "data": { "type": "object", "description": "The order.", "properties": { "orderId": { "type": "string" }, "refId": { "type": "string", "description": "Your reference from estamp-create-v1." }, "type": { "type": "string" }, "status": { "type": "string", "description": "IN_PROGRESS, then FULFILLED (stamp issued; certificate ready) or CONSUMED (stamp used against a document). Treat both FULFILLED and CONSUMED as done." }, "eStampId": { "type": "string", "description": "Present once issued." }, "stampCertificateUrl": { "type": "string", "description": "Link to the stamped certificate PDF, present once FULFILLED. Time-limited: download and store the PDF straight away; call this API again for a fresh link." }, "orderItems": { "type": "array", "description": "One per stamp, each with its own certificateNo, eStampId and stampCertificateUrl (null until issued), plus stateCode, stampDutyAmount, stampType, purpose, firstParty, secondParty, stampDutyPaidBy." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "status": "E-stamp order details fetched successfully.", "data": { "orderId": "SPRAV000001", "type": "SINGLE", "refId": "LOAN-2026-000123", "status": "FULFILLED", "createdAt": "2026-10-20T10:00:00.000Z", "updatedAt": "2026-10-20T10:02:00.000Z", "eStampId": "sample-estamp-0001", "stampCertificateUrl": "https://apisathi.in/samples/estamp-certificate-sample.pdf", "orderItems": [ { "id": "sample-item-0001", "quantity": 1, "status": "FULFILLED", "amount": "100", "createdAt": "2026-10-20T10:00:00.000Z", "updatedAt": "2026-10-20T10:02:00.000Z", "stateCode": "RJ", "stampDutyAmount": 100, "stampType": "ESTAMP", "taxCharges": 30, "considerationPrice": 0, "purpose": "Loan agreement", "articleId": 12, "firstParty": "Sample Lender Pvt Ltd", "secondParty": "Sample Borrower", "stampDutyPaidBy": "FIRST_PARTY", "articleNumber": "5(h)", "certificateNo": "IN-SAMPLE-000001", "stampCertificateUrl": "https://apisathi.in/samples/estamp-certificate-sample.pdf", "eStampId": "sample-estamp-0001", "stampWithAttachment": null } ] } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/device-lock-v1": { "post": { "operationId": "deviceLockV1", "tags": [ "mobile" ], "summary": "Mobile Lock — Lock", "description": "Lock a financed handset remotely. Built for device finance and phone EMI: when a borrower defaults, the handset is restricted until they pay.\n\nTHE HANDSET MUST BE ENROLLED FIRST. Locking works against a `key_id` issued when the device was enrolled and provisioned with the on-device agent. You cannot lock an arbitrary phone by IMEI — enrolment happens at the point of sale, or on a device the borrower hands over for provisioning.\n\nLOCKING IS ASYNCHRONOUS. A 200 means the instruction was accepted, not that the screen is already locked — the handset applies it when it next reaches the network. The response carries `state` (PENDING or COMPLETE). Confirm with device-control-status-v1 rather than assuming; a phone that is switched off or out of coverage will report PENDING for as long as it stays that way.\n\nUse device-unlock-v1 to release. Every action is recorded in device-action-history-v1, which is the audit trail you will want in a dispute.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key_id" ], "properties": { "key_id": { "type": "string", "description": "Key id issued when the handset was enrolled." } } }, "example": { "key_id": "00000194-f02d-b777-99b8-c2402db3f6ca" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "description": "False only if the upstream reported FAILED." }, "state": { "type": "string", "description": "PENDING or COMPLETE. PENDING is normal." } } }, "example": { "accepted": true, "state": "PENDING" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/device-unlock-v1": { "post": { "operationId": "deviceUnlockV1", "tags": [ "mobile" ], "summary": "Mobile Lock — Unlock", "description": "Release a locked handset. Same asynchronous behaviour as device-lock-v1 — a 200 means the instruction was accepted, not that the borrower can already use the phone.\n\nCONFIRM BEFORE YOU TELL THE CUSTOMER. Poll device-control-status-v1 until the LOCK control reads unlocked. Telling a borrower their phone is unlocked while it is still restricted is the single most common support complaint on device finance, and it is avoidable.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key_id" ], "properties": { "key_id": { "type": "string", "description": "Key id issued when the handset was enrolled." } } }, "example": { "key_id": "00000194-f02d-b777-99b8-c2402db3f6ca" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "state": { "type": "string", "description": "PENDING or COMPLETE." } } }, "example": { "accepted": true, "state": "PENDING" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/device-control-status-v1": { "post": { "operationId": "deviceControlStatusV1", "tags": [ "mobile" ], "summary": "Mobile Lock — Status", "description": "The current on/off state of every control on an enrolled handset, including the handset lock. This is how you confirm a lock or unlock actually landed, since both are applied asynchronously.\n\nReturns one entry per control with `name` and `action_status`. The handset lock is the entry named LOCK.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key_id" ], "properties": { "key_id": { "type": "string", "description": "Key id issued when the handset was enrolled." } } }, "example": { "key_id": "00000194-f02d-b777-99b8-c2402db3f6ca" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "controls": { "type": "array", "description": "One entry per control." } } }, "example": { "controls": [ { "id": "02bc8d82-3ec9-4fdc-8cc5-e6887f332266", "name": "LOCK", "action_status": "on" }, { "id": "9e27bcfd-6563-4d31-9587-8c97f6721315", "name": "WHATSAPP_BUSINESS", "action_status": "on" } ] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/device-action-history-v1": { "post": { "operationId": "deviceActionHistoryV1", "tags": [ "mobile" ], "summary": "Mobile Lock — Action History", "description": "Every control action ever applied to a handset, with status and timestamps. This is the audit trail for disputes — it shows who locked what and when, and whether each instruction completed.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key_id" ], "properties": { "key_id": { "type": "string", "description": "Key id issued when the handset was enrolled." } } }, "example": { "key_id": "00000194-f02d-b777-99b8-c2402db3f6ca" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "description": "Most recent first." } } }, "example": { "actions": [ { "id": "00000195-183e-8f87-921c-e20cc17282c1", "action": "UNLOCKED", "status": "COMPLETED", "created_at": 1739868508039 }, { "id": "00000195-183e-01ae-a4d3-2a72dcdc3bf6", "action": "LOCKED", "status": "COMPLETED", "created_at": 1739868471726 } ] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/device-list-v1": { "post": { "operationId": "deviceListV1", "tags": [ "mobile" ], "summary": "Mobile Lock — Enrolled Devices", "description": "List the handsets enrolled under your account with their key ids and status. Use it to recover a `key_id` you did not store against your loan record.\n\nReference lookup, priced at a nominal rate.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array" }, "count": { "type": "number" } } }, "example": { "count": 0, "devices": [] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/aadhaar-digilocker-init-v1": { "post": { "operationId": "aadhaarDigilockerInitV1", "tags": [ "kyc" ], "summary": "Aadhaar DigiLocker — Start", "description": "Start a consented Aadhaar verification. Returns a `kyc_url` — send your customer there and they authenticate with UIDAI directly, entering their Aadhaar number and OTP on the government screen.\n\nYOU NEVER SEE THE AADHAAR NUMBER OR THE OTP. That is the difference between this and raw OKYC, and it is why this flow is usually the easier one to get signed off internally. What you get back at the end is a masked Aadhaar number plus the verified demographics.\n\nTWO STEPS, TWO CALLS. This one issues the link. Once the customer finishes, call aadhaar-digilocker-fetch-v1 with the `transaction_id` returned here to collect the result. Store that id against your application record — without it you cannot retrieve the verification.\n\n`uid` is YOUR reference and must be unique. A repeat is rejected, which is what makes retries safe. Supply `mobile` or `emailId` (at least one); `redirectionUrl` is where the customer lands afterwards, and receives `txnId` plus either `success=true` or `error_code` and `errMsg`.\n\nBilled per link issued. The verification itself is billed on the fetch call.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "Your own unique reference, max 80 chars. Word characters, dots, @ and hyphens only. A repeat is rejected." }, "mobile": { "type": "string", "description": "Customer mobile, exactly 10 digits starting 6-9. Supply this or emailId." }, "emailId": { "type": "string", "description": "Customer email. Supply this or mobile." }, "firstName": { "type": "string", "description": "Optional, max 45 chars." }, "lastName": { "type": "string", "description": "Optional, max 45 chars." }, "isSendOtp": { "type": "boolean", "description": "Have the link delivered to the customer directly." }, "isHideExplanationScreen": { "type": "boolean", "description": "Skip the explanation page." }, "redirectionUrl": { "type": "string", "description": "Where the customer lands after finishing or failing. Max 512 chars." } } }, "example": { "uid": "loan-application-48213", "mobile": "9876543210", "redirectionUrl": "https://yourapp.example/kyc-done" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Pass this to aadhaar-digilocker-fetch-v1. Store it." }, "kyc_url": { "type": "string", "description": "Send the customer here." }, "short_url": { "type": "string", "description": "Shortened form of the same link." }, "verified": { "type": "boolean", "description": "The link was issued." } } }, "example": { "verified": true, "transaction_id": "873585497344017339", "kyc_url": "https://digilocker.example/?token=eyJhbGciOiJSUzI1NiJ9...", "short_url": "https://smler.example/UA1UhGHvwi" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/aadhaar-digilocker-fetch-v1": { "post": { "operationId": "aadhaarDigilockerFetchV1", "tags": [ "kyc" ], "summary": "Aadhaar DigiLocker — Fetch Result", "description": "Collect the verified record once your customer has completed DigiLocker. Call it with the `transaction_id` from aadhaar-digilocker-init-v1.\n\nTHE AADHAAR NUMBER IS MASKED and always will be — the full number is never returned by this flow. You receive name, date of birth, gender, care-of, a structured address and a base64 photo.\n\nPOLL, DO NOT ASSUME. Until the customer finishes, this returns 422 with \"The given transaction id for digilocker is not success\". That is normal and is not an error on your side — it means they have not completed the UIDAI screens yet. Poll after your redirect fires, or on a sensible interval.\n\nThree outcomes are the CUSTOMER’s and not a fault: they declined consent, their DigiLocker account holds no eAadhaar, or they did not select the Aadhaar document. Treat those as a failed verification rather than a retryable error.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "pattern": "^[0-9]{6,32}$", "description": "The transaction_id returned by aadhaar-digilocker-init-v1 — a long number, e.g. 304842915616921275. Not the kyc_url, not the short link, not your uid." } } }, "example": { "transaction_id": "873585497344017339" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "THE FIELD TO BRANCH ON. true = the customer completed DigiLocker and the record below is UIDAI-verified. Anything else is not a successful verification." }, "status": { "type": "string", "description": "The source's own status code, passed through. On success this is the single letter \"s\" — not \"SUCCESS\". Do not string-match it; use `verified`." }, "masked_aadhaar": { "type": "string", "description": "Masked. Never the full number." }, "name": { "type": "string" }, "dob": { "type": "string" }, "gender": { "type": "string" }, "care_of": { "type": "string" }, "address": { "type": "object", "description": "house, street, loc, dist, state, pc and more." }, "photo_base64": { "type": "string", "description": "Base64 photo from the Aadhaar record." }, "documents": { "type": "array", "description": "The DigiLocker files behind the record — signed, time-limited links (`docLink`) with `docType` and `docExtension` (xml, pdf)." } } }, "example": { "verified": true, "status": "s", "masked_aadhaar": "XXXXXXXX1234", "name": "RAHUL VERMA", "dob": "1990-04-12", "gender": "M", "address": { "house": "12", "street": "MG Road", "dist": "Jaipur", "state": "Rajasthan", "pc": "302001" } } } } }, "400": { "description": "You sent something other than the transaction_id — usually the kyc_url, the short link, or your own uid. The transaction_id is the long number in the Start response. Rejected before any lookup; not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "Well-formed, but no verification exists with that id. Definitive — a typo, or an id from a different Start call. Not charged. Do not retry the same value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The customer has NOT finished DigiLocker yet. This is the normal state between Start and completion, not a fault. Not charged. Poll again after your redirect fires, or on a sensible interval.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/lead-enrich-v1": { "post": { "operationId": "leadEnrichV1", "tags": [ "kyc" ], "summary": "Lead Enrichment", "description": "One call that turns a lead into a profile. Send a mobile number — and a PAN if you have one — and we run the relevant lookups across the catalogue and return a single merged result: employment, GST, MSME, directorships and company.\n\nTHE SECOND HOP IS THE POINT. Identifiers discovered in the first pass are followed automatically: a DIN found from the PAN fetches director details, a CIN fetches company master data. You never round-trip to chase them yourself.\n\nPRICING IS NOT FIXED — READ THIS BEFORE BUDGETING. You pay the normal price of each sub-lookup that SUCCEEDED, and nothing for the ones that failed or were skipped. There is no separate orchestration fee. The price shown on this page is the basic-tier FLOOR; a full-tier call on a rich lead costs considerably more. Every response itemises each lookup and what it cost in `lookups[]`, and `totalSalePaise` is exactly what you were billed — so every invoice line traces back to a lookup.\n\nWHAT COUNTS AS BILLABLE: a lookup that returns a definitive \"no record\" IS billed — the source did the work, and `verified: false` is still information. A lookup that FAILED (upstream error) or was SKIPPED (you did not supply the input, or that source is unavailable) costs nothing.\n\nTIMING: basic returns in 1-3s. Full includes the MSME lookup, which is currently slow (24-27s), so set your client timeout to at least 45 seconds for `tier: \"full\"`.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "Borrower mobile number. Formatting is stripped; the last 10 digits are used." }, "pan": { "type": "string", "description": "Optional but high value. Unlocks PAN verification, GSTIN-by-PAN, directorships and company lookups. Without it only the mobile-based lookups run." }, "tier": { "type": "string", "enum": [ "basic", "standard", "full" ], "description": "basic = employment + GST by mobile. standard = adds PAN verification, GSTIN by PAN, directorships and director detail. full = adds MSME/Udyam, company by PAN, company and GST detail. Defaults to basic. Tiers are cumulative." } }, "additionalProperties": false }, "example": { "mobile": "9876543210", "pan": "ABCDE1234F", "tier": "standard" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "type": "string", "description": "The tier that was actually run." }, "profile": { "type": "object", "description": "Merged enrichment. Keys appear only when that lookup succeeded: employment, gst_by_mobile, pan, gstins, directorships, msme, company_by_pan, and the second-hop director_detail, company_detail, gst_detail." }, "lookups": { "type": "array", "description": "One entry per attempted lookup: { product, status, salePaise, costPaise, reason }. status is ok | no_data | failed | skipped." }, "totalSalePaise": { "type": "number", "description": "What you were billed — the sum of successful lookups only." } }, "additionalProperties": true }, "example": { "tier": "standard", "profile": { "pan": { "verified": true, "name": "RAHUL VERMA" }, "employment": { "uan": "XXXXXXXX1234", "employer": "ACME PRIVATE LIMITED" }, "directorships": { "din": "09999999" }, "director_detail": { "name": "RAHUL VERMA", "companies": 2 } }, "lookups": [ { "product": "uan-basic-v3", "status": "ok", "salePaise": 450, "costPaise": 150 }, { "product": "contact-to-gst-v1", "status": "no_data", "salePaise": 210, "costPaise": 70 }, { "product": "pan-verification-v1", "status": "ok", "salePaise": 240, "costPaise": 80 }, { "product": "gstin-by-pan-v1", "status": "failed", "salePaise": 0, "costPaise": 0, "reason": "VENDOR_ERROR" }, { "product": "pan-to-din-v1", "status": "ok", "salePaise": 135, "costPaise": 45 }, { "product": "din-basic-v1", "status": "ok", "salePaise": 150, "costPaise": 50 } ], "totalSalePaise": 1185 } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/esign-status-v1": { "post": { "operationId": "esignStatusV1", "tags": [ "esign" ], "summary": "e-Sign — Request Status & Signed Document", "description": "Fetch the current status of a signing request created with esign-create-v1, and once signed, the signed PDF plus the signer verification details.\n\nPASS THE PER-SIGNER `request_id`, NOT THE GROUP ID. esign-create-v1 returns one `request_id` per signer inside `requests[]`, plus a single `group_id` for the envelope. This endpoint takes the per-signer id; the group id returns 404. For a two-party document you poll twice, once per signer.\n\nTHE SIGNED URL EXPIRES IN 24 HOURS. `signed_url` is a time-limited link, not permanent storage. Download the PDF and store it in your own system as soon as `signed` is true — do not persist the URL and expect it to work tomorrow.\n\nEVIDENCE ARTEFACT: for an Aadhaar signature the response carries `verified_name` (the name held against the Aadhaar record), `name_match_score` (0-1, how closely it matches the name you supplied) and `certifying_authority` (the licensed CA that issued the signature). Together with the signed PDF these are what make the signature defensible under §3A of the IT Act. A low `name_match_score` on an otherwise SUCCESSful signature is worth reviewing before you rely on the document.\n\nPolling: signing happens after esign-create-v1 returns, so poll this until `signed` is true or the request expires (`expires_at`, 7 days by default). Priced at a nominal rate so polling is cheap, but poll sensibly — every few seconds, not in a tight loop.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id" ], "properties": { "request_id": { "type": "string", "description": "The per-signer request_id from esign-create-v1 `requests[].request_id`. NOT the group_id." } }, "additionalProperties": false }, "example": { "request_id": "6a79b62d04efdfca72af83b8" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Upstream transaction state, e.g. GATEWAY_OPENED (link opened, not yet signed), PAUSED (waiting on an earlier signer in the order), SUCCESS (signed)." }, "signed": { "type": "boolean", "description": "True only when the signature is complete." }, "signed_url": { "type": "string", "description": "Time-limited link to the signed PDF. EXPIRES IN 24 HOURS — download it." }, "signed_at": { "type": "string" }, "signer_name": { "type": "string", "description": "The name you supplied." }, "verified_name": { "type": "string", "description": "The name held against the Aadhaar record." }, "name_match_score": { "type": "number", "description": "0-1 similarity between signer_name and verified_name." }, "certifying_authority": { "type": "string", "description": "The licensed CA that issued the signature." }, "expires_at": { "type": "string", "description": "When the signing request lapses." } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "signed": true, "signed_url": "https://storage.example.com/…_signed?…expires…", "signed_at": "2026-08-10T11:33:27.851Z", "signer_name": "Rahul Verma", "verified_name": "Rahul K Verma", "name_match_score": 0.93, "certifying_authority": "EMUDHRA", "expires_at": "2026-08-17T11:29:49.065Z" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "No signing request exists for that request_id. Definitive — check you sent the per-signer request_id and not the group_id. Do not retry the same value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/esign-create-v1": { "post": { "operationId": "esignCreateV1", "tags": [ "esign" ], "summary": "e-Sign — Create Signing Request", "description": "Send a PDF for legally-valid electronic signature under the IT Act.\n\nPRICING IS PER SIGNATORY, not per request. One call can carry several signers, and each is a separate signing transaction — its own request_id, its own invitation, its own Aadhaar/DSC authentication. The price shown is the rate for ONE signatory; a request is billed at that rate × the number of entries in `signers`. A two-party NDA therefore costs twice the listed rate. Your wallet must cover the full amount before the request is created, or the call returns 402 INSUFFICIENT_BALANCE and nothing is sent.\n\nEach signer gets their own `signing_url` and authenticates by Aadhaar OTP, WhatsApp or auto-DSC (`signer_auth_type`). You receive a `group_id` for the whole envelope and a per-signer `request_id`.\n\nINVITES ARE SENT FOR YOU. Each signer is emailed/messaged a signing invitation automatically, and the response reports `invitation_status` per signer. You also receive a `signing_url` per signer, so you can additionally surface the link in your own UI if you prefer — but you do not have to deliver it for signing to happen.\n\nCOMPLETION. Signing happens after this call returns, so the response tells you the request was created, NOT that anything is signed. Track completion by polling, or register a callback and treat it as a prompt to re-check rather than as proof — never release a document on the strength of an unverified callback alone.\n\n`sign_coordinates` places the signature block on the page (x/y/page_num). Omit it to use the provider default position.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document", "signers" ], "properties": { "document": { "type": "object", "description": "The PDF to be signed.", "required": [ "name", "data" ], "properties": { "name": { "type": "string", "description": "File name, e.g. nda.pdf" }, "data": { "type": "string", "description": "Base64-encoded PDF." } } }, "signers": { "type": "array", "description": "One entry per signer; each receives their own signing_url.", "items": { "type": "object", "required": [ "signer_name", "signer_email", "signer_phone_number", "signer_auth_type" ], "properties": { "signer_name": { "type": "string" }, "signer_email": { "type": "string" }, "signer_phone_number": { "type": "string", "description": "With country code, e.g. +919876543210." }, "signer_auth_type": { "type": "string", "enum": [ "AADHAAR", "WHATSAPP", "AUTO_DSC" ], "description": "How the signer proves identity." }, "signer_city": { "type": "string" }, "signer_purpose": { "type": "string" }, "sign_coordinates": { "type": "array", "description": "REQUIRED. Where the signature block is stamped: { x_coord, y_coord, page_num }. Omitting it is rejected.", "items": { "type": "object", "properties": { "x_coord": { "type": "number" }, "y_coord": { "type": "number" }, "page_num": { "type": "number" } } } } } } } } }, "example": { "document": { "name": "nda.pdf", "data": "" }, "signers": [ { "signer_name": "Rahul Verma", "signer_email": "rahul@example.com", "signer_phone_number": "+919876543210", "signer_auth_type": "AADHAAR", "signer_purpose": "Borrower", "sign_coordinates": [ { "x_coord": 100, "y_coord": 100, "page_num": 1 } ] } ] } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "string", "description": "Identifies the whole signing envelope." }, "requests": { "type": "array", "description": "Per-signer request_id and signing_url. Deliver these links yourself." }, "expires_at": { "type": "string" }, "webhook_security_key": { "type": "string" } }, "additionalProperties": true }, "example": { "group_id": "6a79b62d04efdfca72af83b7", "requests": [ { "request_id": "6a79b62d04efdfca72af83b8", "signer_name": "Rahul Verma", "signer_email": "rahul@example.com", "signer_phone_number": "+919876543210", "signer_auth_type": "AADHAAR", "signer_auth_mode": "OTP", "signing_order": 1, "invitation_status": "INVITATION_SUCCESS", "signing_url": "https://esign.example.com/v5/viewer/6a79b62d04efdfca72af83b8" } ], "expires_at": "2026-08-17T11:29:49.065+00:00", "webhook_security_key": "6a56499c-0000-0000-0000-000000000000" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/abb-daily-v1": { "post": { "operationId": "abbDailyV1", "tags": [ "ai" ], "summary": "Average Bank Balance (Daily)", "description": "Average Bank Balance (ABB) computed on a DAILY basis from a bank-statement PDF. We reconstruct the end-of-day (EOD) balance for every calendar day in the statement period — carrying the last known balance forward across days with no transactions — and return the day-weighted mean (the classic \"Average Monthly Balance\" a bank computes), plus a per-month breakdown.\n\nSingle synchronous call: POST a base64 PDF, get the ABB back. Works across banks with no per-bank templates. Digital/native PDFs only (not scans). Billing: charged once per successful call; failures (422) are not charged.\n\nTIMING: parse time scales with the number of transactions, not the page count. A 3-month statement typically returns in 15-30s; a dense 12-month statement (900+ rows) measured 64s end to end. Set your client timeout to at least 120s. A short client timeout is the most common integration failure here — the call completes on our side and you are charged for it, but you never see the result.\n\nDATE-WISE ABB: pass `dates` (e.g. [5,10,15,20,25,30]) to also get the end-of-day balance on those specific days of every month — the figures banking partners assess against. Any combination of days 1-31 is supported, and the usual monthly figures are returned alongside, not instead. The response adds an `on_dates` block: `months[]` (the balance for each requested day in each month, plus that month average), an overall `average_balance` across every sampled point, and `missing[]`. A requested day that the statement does not cover — including the 29th-31st in a short month such as February — is listed in `missing` and NEVER substituted with a nearby day, so a lender never assesses against a date that was not actually measured. Date-wise sampling costs nothing extra: it is a parameter on the same call, not a separate product.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pdf_base64" ], "properties": { "pdf_base64": { "type": "string", "description": "Base64-encoded bank-statement PDF (digital/native, not a scan). Max 15MB." }, "password": { "type": "string", "description": "PDF password, if the statement is locked." }, "dates": { "type": "array", "description": "Optional. Days of the month to sample the balance on, e.g. [5, 15, 25]. Lenders differ on which dates their banking partner assesses ABB against (5/10/15, 5/15/25 and 20/25/30 are all common). Returns an `on_dates` block alongside the usual figures.", "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "maxItems": 31 } }, "additionalProperties": false }, "example": { "pdf_base64": "", "dates": [ 5, 15, 25 ] } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "description": "Holder, masked account no., bank, IFSC." }, "basis": { "type": "string", "description": "Always 'daily' for this product." }, "average_balance": { "type": "number", "description": "Headline ABB: day-weighted mean of daily EOD balances. null if no balances found." }, "currency": { "type": "string" }, "period": { "type": "object", "description": "from, to, and days = number of calendar days averaged." }, "breakdown": { "type": "array", "description": "Per-month buckets: { period: 'YYYY-MM', average_balance, min_balance, max_balance, days }." }, "meta": { "type": "object", "description": "engine, transactions, had_running_balance, pages." }, "on_dates": { "type": "object", "description": "Present ONLY when `dates` was supplied: the end-of-day balance on each requested day in every month, a per-month average, an overall average, and a `missing` list of requested dates the statement does not cover (never substituted with a nearby day)." } }, "additionalProperties": true }, "example": { "account": { "account_holder": "RAHUL VERMA", "account_number": "XXXXXX4321", "bank": "HDFC Bank", "ifsc": "HDFC0001234" }, "basis": "daily", "average_balance": 61250.5, "currency": "INR", "period": { "from": "2026-04-01", "to": "2026-06-30", "days": 91 }, "breakdown": [ { "period": "2026-04", "average_balance": 58200, "min_balance": 12400, "max_balance": 96000, "days": 30 }, { "period": "2026-05", "average_balance": 60100.5, "min_balance": 15300, "max_balance": 99500, "days": 31 }, { "period": "2026-06", "average_balance": 65450, "min_balance": 18900, "max_balance": 102300, "days": 30 } ], "on_dates": { "days": [ 5, 15, 25 ], "average_balance": 61980.25, "months": [ { "period": "2026-04", "samples": [ { "day": 5, "date": "2026-04-05", "balance": 58200 }, { "day": 15, "date": "2026-04-15", "balance": 62400 }, { "day": 25, "date": "2026-04-25", "balance": 64100 } ], "average_balance": 61566.67 } ], "missing": [] }, "meta": { "engine": "apisathi-abb-v1", "transactions": 16, "had_running_balance": true, "pages": 4 } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/abb-weekly-v1": { "post": { "operationId": "abbWeeklyV1", "tags": [ "ai" ], "summary": "Average Bank Balance (Weekly)", "description": "Average Bank Balance (ABB) computed on a WEEKLY basis from a bank-statement PDF. We reconstruct the end-of-day balance for every day, group days into ISO weeks, average each week, and return the week-weighted mean of those weekly averages — plus a per-week breakdown. Because each week counts equally (regardless of how many days it holds), the weekly ABB differs from the daily ABB, mainly at partial weeks at the start/end of the period.\n\nSingle synchronous call: POST a base64 PDF, get the ABB back. Works across banks with no per-bank templates. Digital/native PDFs only (not scans). Billing: charged once per successful call; failures (422) are not charged.\n\nTIMING: parse time scales with the number of transactions, not the page count. A 3-month statement typically returns in 15-30s; a dense 12-month statement (900+ rows) measured 64s end to end. Set your client timeout to at least 120s. A short client timeout is the most common integration failure here — the call completes on our side and you are charged for it, but you never see the result.\n\nDATE-WISE ABB: pass `dates` (e.g. [5,10,15,20,25,30]) to also get the end-of-day balance on those specific days of every month — the figures banking partners assess against. Any combination of days 1-31 is supported, and the usual monthly figures are returned alongside, not instead. The response adds an `on_dates` block: `months[]` (the balance for each requested day in each month, plus that month average), an overall `average_balance` across every sampled point, and `missing[]`. A requested day that the statement does not cover — including the 29th-31st in a short month such as February — is listed in `missing` and NEVER substituted with a nearby day, so a lender never assesses against a date that was not actually measured. Date-wise sampling costs nothing extra: it is a parameter on the same call, not a separate product.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pdf_base64" ], "properties": { "pdf_base64": { "type": "string", "description": "Base64-encoded bank-statement PDF (digital/native, not a scan). Max 15MB." }, "password": { "type": "string", "description": "PDF password, if the statement is locked." }, "dates": { "type": "array", "description": "Optional. Days of the month to sample the balance on, e.g. [5, 15, 25]. Lenders differ on which dates their banking partner assesses ABB against (5/10/15, 5/15/25 and 20/25/30 are all common). Returns an `on_dates` block alongside the usual figures.", "items": { "type": "integer", "minimum": 1, "maximum": 31 }, "maxItems": 31 } }, "additionalProperties": false }, "example": { "pdf_base64": "", "dates": [ 5, 15, 25 ] } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "description": "Holder, masked account no., bank, IFSC." }, "basis": { "type": "string", "description": "Always 'weekly' for this product." }, "average_balance": { "type": "number", "description": "Headline ABB: week-weighted mean of ISO-week average balances. null if no balances found." }, "currency": { "type": "string" }, "period": { "type": "object", "description": "from, to, and days = number of calendar days averaged." }, "breakdown": { "type": "array", "description": "Per-week buckets: { period: 'YYYY-Www' (ISO week), average_balance, min_balance, max_balance, days }." }, "meta": { "type": "object", "description": "engine, transactions, had_running_balance, pages." }, "on_dates": { "type": "object", "description": "Present ONLY when `dates` was supplied: the end-of-day balance on each requested day in every month, a per-month average, an overall average, and a `missing` list of requested dates the statement does not cover (never substituted with a nearby day)." } }, "additionalProperties": true }, "example": { "account": { "account_holder": "RAHUL VERMA", "account_number": "XXXXXX4321", "bank": "HDFC Bank", "ifsc": "HDFC0001234" }, "basis": "weekly", "average_balance": 61980.25, "currency": "INR", "period": { "from": "2026-04-01", "to": "2026-06-30", "days": 91 }, "breakdown": [ { "period": "2026-W14", "average_balance": 57800, "min_balance": 12400, "max_balance": 71000, "days": 6 }, { "period": "2026-W15", "average_balance": 59100, "min_balance": 41000, "max_balance": 78000, "days": 7 }, { "period": "2026-W16", "average_balance": 62400, "min_balance": 46500, "max_balance": 84000, "days": 7 } ], "on_dates": { "days": [ 5, 15, 25 ], "average_balance": 61980.25, "months": [ { "period": "2026-04", "samples": [ { "day": 5, "date": "2026-04-05", "balance": 58200 }, { "day": 15, "date": "2026-04-15", "balance": 62400 }, { "day": 25, "date": "2026-04-25", "balance": 64100 } ], "average_balance": 61566.67 } ], "missing": [] }, "meta": { "engine": "apisathi-abb-v1", "transactions": 16, "had_running_balance": true, "pages": 4 } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/aadhaar-to-masked-pan": { "post": { "operationId": "aadhaarToMaskedPan", "tags": [ "kyc" ], "summary": "Aadhaar to Masked PAN", "description": "Returns the masked PAN linked to an Aadhaar number and whether a link exists — the reverse of PAN to Masked Aadhaar. No OTP. Use it to pre-fill PAN when only Aadhaar is known. Not charged when nothing is linked.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "aadhaar" ], "properties": { "aadhaar": { "type": "string", "pattern": "^[0-9]{12}$" } }, "additionalProperties": false }, "example": { "aadhaar": "999912341234" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "linked": { "type": "boolean" }, "masked_pan": { "type": "string" } } }, "example": { "verified": true, "linked": true, "masked_pan": "ABXXXXXX4E" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/cin-advanced-v1": { "post": { "operationId": "cinAdvancedV1", "tags": [ "kyb" ], "summary": "CIN (COI) Validation Advance", "description": "Validate a company CIN and fetch enriched MCA master data, directors and charges.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cin" ], "properties": { "cin": { "type": "string", "description": "Corporate Identification Number (CIN/COI)" } } }, "example": { "cin": "U72900KA2018PTC114387" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cin": { "type": "string" }, "roc_code": { "type": "string" }, "verified": { "type": "boolean" }, "company_name": { "type": "string" } } }, "example": { "cin": "U72900KA2018PTC114387", "roc_code": "sample", "verified": true, "company_name": "Rohit Sharma" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/cin-basic-v1": { "post": { "operationId": "cinBasicV1", "tags": [ "kyb" ], "summary": "CIN (COI) Validation Basic", "description": "Validate a company CIN and fetch master company data from MCA.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cin" ], "properties": { "cin": { "type": "string", "description": "Corporate Identification Number (CIN/COI)" } } }, "example": { "cin": "U72900KA2018PTC114387" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cin": { "type": "string" }, "roc_code": { "type": "string" }, "verified": { "type": "boolean" }, "company_name": { "type": "string" } } }, "example": { "cin": "U72900KA2018PTC114387", "roc_code": "sample", "verified": true, "company_name": "Rohit Sharma" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/cin-enhanced-v1": { "post": { "operationId": "cinEnhancedV1", "tags": [ "kyb" ], "summary": "CIN Enhanced", "description": "Deep MCA company profile for a CIN: master data, directors, charges and signatories.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cin" ], "properties": { "cin": { "type": "string", "description": "Corporate Identification Number (CIN)" } } }, "example": { "cin": "U72900KA2018PTC114387" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cin": { "type": "string" }, "result": { "type": "object" }, "verified": { "type": "boolean" }, "company_name": { "type": "string" } } }, "example": { "cin": "U72900KA2018PTC114387", "result": {}, "verified": true, "company_name": "Rohit Sharma" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/cin-to-pan-v1": { "post": { "operationId": "cinToPanV1", "tags": [ "kyb" ], "summary": "CIN to PAN", "description": "Resolve the company PAN linked to a CIN.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cin" ], "properties": { "cin": { "type": "string", "description": "Corporate Identification Number (CIN)" } } }, "example": { "cin": "U72900KA2018PTC114387" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pan": { "type": "string" }, "verified": { "type": "boolean" } } }, "example": { "pan": "ABCDE1234F", "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/company-to-cin-v1": { "post": { "operationId": "companyToCinV1", "tags": [ "kyb" ], "summary": "Company Name to CIN", "description": "Resolve candidate CINs for a company name with match scores.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_name", "output_count" ], "properties": { "company_name": { "type": "string", "description": "Company name to resolve" }, "output_count": { "type": "string", "description": "Number of CIN entries to return (Min 10, Max 50)" } } }, "example": { "company_name": "Rohit Sharma", "output_count": "10" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array" }, "verified": { "type": "boolean" } } }, "example": { "result": [], "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/company-to-pan-v1": { "post": { "operationId": "companyToPanV1", "tags": [ "kyb" ], "summary": "Company Name to PAN", "description": "Resolve candidate company PANs for a company name with match scores.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_name", "output_count" ], "properties": { "company_name": { "type": "string", "description": "Company name to resolve" }, "output_count": { "type": "string", "description": "Number of companies to return" } } }, "example": { "company_name": "Rohit Sharma", "output_count": "10" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pan_list": { "type": "array" }, "verified": { "type": "boolean" }, "company_name": { "type": "string" } } }, "example": { "pan_list": [], "verified": true, "company_name": "Rohit Sharma" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/contact-to-gst-v1": { "post": { "operationId": "contactToGstV1", "tags": [ "kyb" ], "summary": "Contact to GST", "description": "Find GSTINs linked to a mobile number with legal/trade names.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "10-digit mobile number linked with the GSTIN" } } }, "example": { "mobile": "9876543210" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "matches": { "type": "array" }, "verified": { "type": "boolean" } } }, "example": { "matches": [], "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/credit-report-cibil-v1": { "post": { "operationId": "creditReportCibilV1", "tags": [ "credit" ], "summary": "CIBIL Credit Report", "description": "Consent-based CIBIL (TransUnion) credit report and score for an individual, looked up by PAN + mobile. Returns the bureau score plus the structured credit report (accounts, enquiries).\n\nCONSENT REQUIRED. You must hold the borrower’s consent for the credit pull before calling, and keep it as evidence. How you collect it is up to you: an OTP (see the Credit Consent OTP SMS API), a signed / e-signed loan application, or a recorded checkbox with timestamp. Mandatory fields: `mobile` (the number linked to the person’s credit record), `pan`, `name`, `gender` (`male`/`female`) and `consent` (must be `\"Y\"`). Optional: `consent_reference` (your application / e-sign / consent-log id, stored with the call as evidence) and `otp` (if you collected consent by OTP). Billed on SUCCESS only. (A downloadable-PDF variant is available separately as CIBIL Credit Report (PDF).) \n\nTIMING: bureau pulls are slow — typical 4-9s, p95 ~8.5s. Our upstream timeout is 15s, so set your client timeout to at least 20s. A client timeout below ~10s will surface as a failure on your side for calls we complete successfully. Timeouts are never charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile", "pan", "name", "gender", "consent" ], "properties": { "mobile": { "type": "string", "description": "The mobile number the person has REGISTERED with the credit bureau — not just any number they own. If it is not the credit-linked mobile, the call returns 422 \"invalid_mobile_number\" with no report (and no charge). This is the most common cause of a failed pull.", "pattern": "^[6-9][0-9]{9}$" }, "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$" }, "name": { "type": "string", "description": "Full name of the individual as per PAN" }, "gender": { "type": "string", "enum": [ "male", "female" ], "description": "Required by the bureau — the individual’s gender" }, "consent": { "type": "string", "enum": [ "Y" ], "description": "Must be \"Y\" — explicit end-user consent for the bureau pull" }, "otp": { "type": "string", "pattern": "^[0-9]{4,6}$", "description": "Optional. Borrower consent OTP, if you collected consent by OTP (e.g. via the Credit Consent OTP SMS API)." }, "consent_reference": { "type": "string", "maxLength": 100, "description": "Optional. Your reference for the consent you hold (application id, e-sign id, consent-log id). Stored with the call as evidence." } } }, "example": { "mobile": "9988776655", "pan": "EKRPR1234F", "name": "Vishal Rathore", "gender": "male", "consent": "Y", "otp": "534216" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "credit_score": { "type": "string", "description": "CIBIL score, e.g. \"744\"" }, "name": { "type": "string" }, "mobile": { "type": "string" }, "pan": { "type": "string" }, "gender": { "type": "string" }, "email": { "type": "string", "description": "Email on the bureau record, if any (often null)" }, "credit_report": { "type": "object", "additionalProperties": true, "description": "Full structured report — score, accounts/tradelines, and enquiries." }, "credit_report_link": { "type": "string", "description": "URL of the PDF credit report — an API Sathi-formatted report (score, summary, every account with 36-month payment history, enquiries) built from the same data as `credit_report`, with identifiers masked. Fetch it with the same X-API-Key header. Does not expire; also downloadable from your call history in the portal." }, "client_id": { "type": "string" } } }, "example": { "verified": true, "credit_score": "744", "name": "VISHAL RATHORE", "mobile": "9988776655", "pan": "EKRPR1234F", "gender": "male", "email": null, "credit_report": { "score": { "score": "744", "scoreName": "CIBILTUSCORE" }, "accounts": [ "… structured account list …" ], "enquiries": [ "… structured enquiry list …" ] }, "credit_report_link": "https://apisathi.in/gw/v1/documents/01a0a8e6-6480-7e90-aba7-4ff96bcb4a53", "client_id": "credit_report_cibil_xxx" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/credit-report-v1": { "post": { "operationId": "creditReportV1", "tags": [ "credit" ], "summary": "Credit Report (Experian)", "description": "Consumer credit report from Experian, pulled by mobile number with explicit borrower consent.\n\nSINGLE CALL — there is NO separate \"send OTP\" / OTP-initiation endpoint. The consent OTP is handled at YOUR end: send an OTP to the borrower’s registered mobile using your own OTP/SMS system, have them confirm it, then pass that same OTP here (in the `otp` field) as proof of consent. The OTP must be UNIQUE per request — reusing the same OTP for the same mobile is rejected as an invalid OTP.\n\n`device_type` and the internal name-lookup flag are set by API Sathi server-side, so you do not send them. Billed on SUCCESS only: a rejected OTP / device_ip / consent / timestamp returns a 4xx and is NOT charged. \n\nTIMING: bureau pulls are slow — typical 4-9s, p95 ~8.5s. Our upstream timeout is 15s, so set your client timeout to at least 20s. A client timeout below ~10s will surface as a failure on your side for calls we complete successfully. Timeouts are never charged.\n\nOPTIONAL FIELDS: `pan`, `date_of_birth` (YYYY-MM-DD) and `email` improve the bureau match; send them in the request BODY (never in headers). `report_type` adds a PDF and/or XML of the report: \"3\" = JSON + PDF link, \"4\" = JSON + PDF + XML links. The links expire after 1 hour, so download and store the file straight away.\n\nRESPONSE: the score is at `credit_score`; the full Experian report is at `report.result_json.INProfileResponse` (accounts in CAIS_Account, enquiries in CAPS). The layout is the Experian bureau format, so it differs from the CIBIL report. `result_code` 102 = no record at the bureau, 103 = name not found for this mobile, 106 = mobile not authenticated by the bureau.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile_no", "first_name", "last_name", "consent_message", "consent_acceptance", "otp", "timestamp", "device_ip" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Za-z]{5}[0-9]{4}[A-Za-z]$", "description": "Optional. Borrower PAN; improves the bureau match." }, "date_of_birth": { "type": "string", "description": "Optional. YYYY-MM-DD." }, "email": { "type": "string", "description": "Optional. Borrower email." }, "report_type": { "type": "string", "enum": [ "0", "2", "3", "4" ], "description": "Optional. 0 = JSON (default), 2 = + XML link, 3 = + PDF link, 4 = + PDF and XML links. Links expire after 1 hour." }, "otp": { "type": "string", "description": "The consent OTP you generated + verified with the borrower at your end. Max 6 digits. Must be unique per request (a reused OTP for the same mobile is rejected)." }, "device_ip": { "type": "string", "description": "The borrower’s device IP (e.g. 203.0.113.10). Must be a valid IP." }, "last_name": { "type": "string", "description": "Borrower last name" }, "mobile_no": { "type": "string", "pattern": "^[6-9][0-9]{9}$", "description": "Borrower mobile number (the one consent was taken on)" }, "timestamp": { "type": "string", "description": "Request time in DDMMYYYY-HH:MM:SS format, e.g. 24072026-14:30:00" }, "first_name": { "type": "string", "description": "Borrower first name" }, "consent_message": { "type": "string", "description": "Consent text; MUST contain the words: I, authorize, Experian, credit, report. e.g. \"I hereby authorize Experian to pull my credit report for loan eligibility purpose\"." }, "consent_acceptance": { "enum": [ "yes", "no" ], "type": "string", "description": "Must be \"yes\" — the borrower accepted consent." } }, "additionalProperties": false }, "example": { "mobile_no": "9876543210", "first_name": "Rahul", "last_name": "Verma", "consent_message": "I hereby authorize Experian to pull my credit report for loan eligibility purpose", "consent_acceptance": "yes", "otp": "534216", "timestamp": "24072026-14:30:00", "device_ip": "203.0.113.10" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credit_score": { "type": "string", "description": "Experian bureau score; null when there is no bureau record." }, "report_pdf_url": { "type": "string", "description": "Present when report_type is 3 or 4. Expires after 1 hour." }, "report_xml_url": { "type": "string", "description": "Present when report_type is 2 or 4." }, "report": { "type": "object" }, "message": { "type": "string" }, "report_pdf": { "type": "string" }, "report_xml": { "type": "string" } } }, "example": { "report": {}, "message": "sample", "report_pdf": "sample", "report_xml": "sample" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/credit-report-crif-v1": { "post": { "operationId": "creditReportCrifV1", "tags": [ "credit" ], "summary": "CRIF Credit Report", "description": "Consumer credit report and score for an individual, pulled by mobile number with explicit borrower consent.\n\nSINGLE CALL — there is NO separate \"send OTP\" endpoint. The consent OTP is handled at YOUR end: send an OTP to the borrower’s registered mobile using your own OTP/SMS system (see the Credit Consent OTP SMS API), have them confirm it, then pass that same OTP here as proof of consent. The OTP must be UNIQUE per request. Billed on SUCCESS only (a successful pull includes the \"no record found\" case). \n\nTIMING: bureau pulls are slow — typical 4-9s, p95 ~8.5s. Our upstream timeout is 15s, so set your client timeout to at least 20s. A client timeout below ~10s will surface as a failure on your side for calls we complete successfully. Timeouts are never charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile_no", "first_name", "last_name", "otp", "timestamp", "device_ip" ], "properties": { "mobile_no": { "type": "string", "pattern": "^[6-9][0-9]{9}$", "description": "Borrower mobile number (the one consent was taken on)" }, "first_name": { "type": "string", "description": "Borrower first name" }, "last_name": { "type": "string", "description": "Borrower last name" }, "otp": { "type": "string", "description": "The consent OTP you generated + verified with the borrower. Max 6 digits, unique per request." }, "timestamp": { "type": "string", "description": "Request time in DDMMYYYY-HH:MM:SS format, e.g. 30072026-14:30:00" }, "device_ip": { "type": "string", "description": "Borrower device IP (e.g. 203.0.113.10). Must be a valid IP." } }, "additionalProperties": false }, "example": { "mobile_no": "9876543210", "first_name": "Rahul", "last_name": "Verma", "otp": "534216", "timestamp": "30072026-14:30:00", "device_ip": "203.0.113.10" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "object", "description": "Structured credit report + score" }, "message": { "type": "string" }, "report_pdf": { "type": "string", "description": "Signed URL to the PDF report (when available)" }, "report_xml": { "type": "string", "description": "Signed URL to the XML report (when available)" } } }, "example": { "report": { "score": "760", "accounts": [ "… structured tradelines …" ] }, "message": "success", "report_pdf": "https://…/crif_report.pdf" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/din-basic-v1": { "post": { "operationId": "dinBasicV1", "tags": [ "kyb" ], "summary": "DIN Validation Basic", "description": "Validate a Director Identification Number and return director name and status.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "din" ], "properties": { "din": { "type": "string", "description": "8-digit Director Identification Number" } } }, "example": { "din": "00001095" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "din": { "type": "string" }, "verified": { "type": "boolean" }, "last_name": { "type": "string" }, "din_status": { "type": "string" }, "first_name": { "type": "string" }, "approval_date": { "type": "string" } } }, "example": { "din": "00001095", "verified": true, "last_name": "Rohit Sharma", "din_status": "sample", "first_name": "Rohit Sharma", "approval_date": "sample" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/din-to-pan-v1": { "post": { "operationId": "dinToPanV1", "tags": [ "kyb" ], "summary": "DIN to PAN", "description": "Resolve the PAN linked to a Director Identification Number (DIN).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "din" ], "properties": { "din": { "type": "string", "description": "8-digit Director Identification Number" } } }, "example": { "din": "00001095" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pan": { "type": "string" }, "verified": { "type": "boolean" } } }, "example": { "pan": "ABCDE1234F", "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/dl-validation-plus": { "post": { "operationId": "dlValidationPlus", "tags": [ "kyc" ], "summary": "Driving Licence Verification Plus", "description": "Everything in Driving Licence Verification plus the holder photo, a split address (house, street, city, district, state, pincode), badge details and the last-transaction date — the version to use when the licence is the primary KYC document. Same inputs.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dl_number", "dob" ], "properties": { "dl_number": { "type": "string", "pattern": "^[A-Za-z0-9/]{13,25}$" }, "dob": { "type": "string", "pattern": "^[0-3][0-9]/[01][0-9]/[12][0-9]{3}$", "description": "DD/MM/YYYY" } }, "additionalProperties": false }, "example": { "dl_number": "RJ1420110012345", "dob": "12/04/1991" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "name": { "type": "string" }, "father_or_husband_name": { "type": "string" }, "dob": { "type": "string" }, "status": { "type": "string" }, "dl_validity": { "type": "object" }, "vehicle_classes": { "type": "array" }, "address": { "type": "string" }, "split_address": { "type": "object" }, "badge_details": { "type": "object" }, "last_transacted_at": { "type": "string" }, "photo_base64": { "type": "string", "description": "Holder photo from the licence record." } } }, "example": { "verified": true, "name": "RAHUL VERMA", "father_or_husband_name": "SURESH VERMA", "dob": "12/04/1991", "status": "Active", "dl_validity": { "non_transport": { "from": "17/07/2017", "to": "16/07/2037" } }, "vehicle_classes": [ { "cov": "LMV" } ], "address": "14, Shanti Niketan, Malviya Nagar, Jaipur", "split_address": { "city": "Jaipur", "district": "Jaipur", "state": "Rajasthan", "pincode": "302017" }, "last_transacted_at": "2024-03-11", "photo_base64": "/9j/4AAQSkZJRg…" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "No record for those details. Definitive; not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/driving-license-v1": { "post": { "operationId": "drivingLicenseV1", "tags": [ "kyc" ], "summary": "Driving License Verification", "description": "Verifies a driving licence against the Sarathi (transport department) record: holder name, date of birth, validity dates, licence classes and issuing authority.\n\nINPUT FORMAT: send `dl_number` exactly as printed but with no spaces or hyphens (e.g. RJ1420110012345), and `dob` as DD/MM/YYYY (e.g. 15/01/1990). Any other date format is rejected with 400 INVALID_REQUEST. Note that dates in the RESPONSE (dob, valid_from, valid_upto) come back as YYYY-MM-DD; that is the output format only.\n\nNOT FOUND: 404 NOT_FOUND means the source has no licence matching that number AND date of birth (usually a wrong date of birth or a typo in the number). It is not a configuration problem and it is NOT charged. Every response, including errors, carries an X-Call-Id header: quote it to support.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dl_number", "dob" ], "properties": { "dob": { "type": "string", "pattern": "^[0-3][0-9]/[01][0-9]/[12][0-9]{3}$", "description": "Date of birth as on the licence, DD/MM/YYYY (e.g. 15/01/1990)." }, "dl_number": { "type": "string", "pattern": "^[A-Za-z0-9/]{13,25}$", "description": "DL number as printed, no spaces or hyphens (e.g. RJ1420110012345)." } }, "additionalProperties": false }, "example": { "dl_number": "RJ1420190001234", "dob": "15/01/1990" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dob": { "type": "string", "format": "date" }, "name": { "type": "string" }, "verified": { "type": "boolean" }, "dl_number": { "type": "string" }, "valid_from": { "type": "string", "format": "date" }, "valid_upto": { "type": "string", "format": "date" }, "vehicle_classes": { "type": "array", "items": { "type": "string" } }, "issuing_authority": { "type": "string" } } }, "example": { "dob": "1990-01-15", "name": "Rohit Sharma", "verified": true, "dl_number": "RJ1420190001234", "valid_from": "1990-01-15", "valid_upto": "1990-01-15", "vehicle_classes": [ "RJ14CV0002" ], "issuing_authority": "sample" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "No licence matches this number and date of birth at the source. Check the DOB (DD/MM/YYYY). Not charged; do not retry unchanged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/gst-enhanced-v1": { "post": { "operationId": "gstEnhancedV1", "tags": [ "kyb" ], "summary": "GST Enhanced", "description": "Enhanced GSTIN intelligence: taxpayer details, contacts, business nature PLUS the full GST return filing history (GSTR1 / GSTR3B / GSTR9 / GSTR9C) with filing dates, status, delayed flag and return-filing frequency. Use this to fetch a business’s GST returns.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin" ], "properties": { "gstin": { "type": "string", "description": "15-character GSTIN", "pattern": "^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[0-9A-Z]{3}$" } } }, "example": { "gstin": "27AAACR5055K1Z7" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "legal_name": { "type": "string" }, "email": { "type": "string" }, "mobile_number": { "type": "string" }, "nature_of_core_business": { "type": "string" }, "aadhaar_verification_flag": { "type": "string" }, "return_filing_frequency": { "type": "array", "description": "Filing frequency (Monthly/Quarterly) per quarter.", "items": { "type": "object", "additionalProperties": true } }, "filing_status": { "type": "array", "description": "Recent GST return filings (GSTR1/3B/9/9C).", "items": { "type": "object", "properties": { "financial_year": { "type": "string" }, "tax_return_period": { "type": "string" }, "return_type": { "type": "string" }, "mode_of_filing": { "type": "string" }, "date_of_filing": { "type": "string" }, "filing_status": { "type": "string" }, "is_delayed": { "type": "boolean" } }, "additionalProperties": true } }, "turnover_summary": { "type": "object", "additionalProperties": true }, "business_places": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "example": { "verified": true, "legal_name": "RELIANCE INDUSTRIES LIMITED", "email": "accounts@example.com", "mobile_number": "98XXXXXXXX", "nature_of_core_business": "Factory / Manufacturing, Retail Business", "aadhaar_verification_flag": "Yes", "return_filing_frequency": [ { "fy": "2026-27", "qtr": "Apr-Jun", "frqncy": "Monthly" } ], "filing_status": [ { "financial_year": "2026-2027", "tax_return_period": "June", "return_type": "GSTR1", "mode_of_filing": "ONLINE", "date_of_filing": "10/07/2026", "filing_status": "Filed", "is_delayed": false }, { "financial_year": "2026-2027", "tax_return_period": "June", "return_type": "GSTR3B", "mode_of_filing": "ONLINE", "date_of_filing": "20/07/2026", "filing_status": "Filed", "is_delayed": false } ], "turnover_summary": { "slab": "Rs. 500 Cr. and above" }, "business_places": [ { "nature": "Principal Place of Business", "address": "..." } ] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/gstin-verify-v1": { "post": { "operationId": "gstinVerifyV1", "tags": [ "kyb" ], "summary": "GSTIN Authentication Advanced", "description": "Authenticate a GSTIN and return taxpayer details, return filings and places of business.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin" ], "properties": { "gstin": { "type": "string", "description": "15-character GSTIN" } } }, "example": { "gstin": "27AAACR5055K1Z7" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gstin": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "legal_name": { "type": "string" }, "trade_name": { "type": "string" }, "constitution": { "type": "string" }, "registration_date": { "type": "string" } } }, "example": { "gstin": "27AAACR5055K1Z7", "status": "sample", "verified": true, "legal_name": "sample", "trade_name": "sample", "constitution": "sample", "registration_date": "sample" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/gstin-basic-v1": { "post": { "operationId": "gstinBasicV1", "tags": [ "kyb" ], "summary": "GSTIN Authentication Basic", "description": "Authenticate a GSTIN and return core taxpayer details.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin" ], "properties": { "gstin": { "type": "string", "description": "15-character GSTIN" } } }, "example": { "gstin": "27AAACR5055K1Z7" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "gstin": { "type": "string" }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "legal_name": { "type": "string" }, "trade_name": { "type": "string" }, "constitution": { "type": "string" }, "registration_date": { "type": "string" } } }, "example": { "gstin": "27AAACR5055K1Z7", "status": "sample", "verified": true, "legal_name": "sample", "trade_name": "sample", "constitution": "sample", "registration_date": "sample" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/gstin-by-pan-v1": { "post": { "operationId": "gstinByPanV1", "tags": [ "kyb" ], "summary": "GSTIN Search by PAN", "description": "List all GSTINs registered against a PAN, optionally filtered by state.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "description": "10-character PAN" }, "state": { "type": "string", "description": "Optional state name filter" }, "state_code": { "type": "string", "description": "Optional state code filter" } } }, "example": { "pan": "ABCDE1234F", "state": "Rajasthan", "state_code": "29" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "verified": { "type": "boolean" }, "gstin_list": { "type": "array" } } }, "example": { "count": 10, "verified": true, "gstin_list": [] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/gstin-to-contact-v1": { "post": { "operationId": "gstinToContactV1", "tags": [ "kyb" ], "summary": "GSTIN to Contact Details", "description": "Fetch the registered mobile and email contact for a GSTIN.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin" ], "properties": { "gstin": { "type": "string", "description": "15-character GSTIN" } } }, "example": { "gstin": "27AAACR5055K1Z7" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "mobile": { "type": "string" }, "verified": { "type": "boolean" } } }, "example": { "email": "user@example.com", "mobile": "9876543210", "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ifsc-lookup-v1": { "post": { "operationId": "ifscLookupV1", "tags": [ "kyc" ], "summary": "IFSC Lookup", "description": "Resolve an IFSC code to its bank, branch, address and payment-rail support.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ifsc" ], "properties": { "ifsc": { "type": "string", "pattern": "^[A-Z]{4}0[A-Z0-9]{6}$" } }, "additionalProperties": false }, "example": { "ifsc": "HDFC0000123" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upi": { "type": "boolean" }, "bank": { "type": "string" }, "city": { "type": "string" }, "ifsc": { "type": "string" }, "imps": { "type": "boolean" }, "micr": { "type": "string" }, "neft": { "type": "boolean" }, "rtgs": { "type": "boolean" }, "state": { "type": "string" }, "branch": { "type": "string" }, "address": { "type": "string" } } }, "example": { "upi": true, "bank": "sample", "city": "Jaipur", "ifsc": "HDFC0000123", "imps": true, "micr": "sample", "neft": true, "rtgs": true, "state": "Rajasthan", "branch": "sample", "address": "MG Road, Jaipur, Rajasthan" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/itr-check": { "post": { "operationId": "itrCheck", "tags": [ "kyc" ], "summary": "ITR Filing Verification", "description": "Whether a PAN has filed income-tax returns, and for which assessment years — acknowledgement number and date per year, with form and filing type where the source has them. A quick income-compliance check for lending and vendor onboarding: no OTP, no consent flow, no document upload.\n\nBoth outcomes are answers and both are billed: `has_filings: true` with the list, or `has_filings: false` when the PAN has never filed.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$" } }, "additionalProperties": false }, "example": { "pan": "ABCPD1234E" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "has_filings": { "type": "boolean" }, "filings": { "type": "array", "description": "Newest first: assessment_year, ack_num, ack_date_time, form_type, filing_type." }, "message": { "type": "string" } } }, "example": { "verified": true, "has_filings": true, "filings": [ { "assessment_year": "2026", "ack_num": "583864160040726", "ack_date_time": "2026-07-04 13:54:10", "form_type": "ITR-1", "filing_type": "Original" }, { "assessment_year": "2025", "ack_num": "571096020200725", "ack_date_time": "2025-07-20 12:47:51", "form_type": "ITR-1", "filing_type": "Original" }, { "assessment_year": "2024", "ack_num": "100529200250724", "ack_date_time": "2024-07-25 15:20:13", "form_type": "ITR-1", "filing_type": "Original" } ] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/masked-mobile-report-v1": { "post": { "operationId": "maskedMobileReportV1", "tags": [ "credit" ], "summary": "Masked Mobile Credit Report", "description": "Credit report against a masked mobile number with consent (Experian, via API Sathi).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile_no", "first_name", "last_name", "consent_message", "consent_acceptance", "otp", "timestamp", "device_ip" ], "properties": { "otp": { "type": "string" }, "device_ip": { "type": "string" }, "last_name": { "type": "string" }, "mobile_no": { "type": "string", "pattern": "^[6-9][0-9]{9}$" }, "timestamp": { "type": "string", "description": "DDMMYYYY-HH:MM:SS" }, "first_name": { "type": "string" }, "consent_message": { "type": "string", "description": "Experian consent; must contain the words I, authorize, Experian, credit, report" }, "consent_acceptance": { "enum": [ "yes", "no" ], "type": "string" } }, "additionalProperties": false }, "example": { "mobile_no": "9876543210", "first_name": "Rohit Sharma", "last_name": "Rohit Sharma", "consent_message": "I hereby provide my consent for verification.", "consent_acceptance": "yes", "otp": "123456", "timestamp": "sample", "device_ip": "sample" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "object" }, "message": { "type": "string" }, "report_pdf": { "type": "string" }, "report_xml": { "type": "string" } } }, "example": { "report": {}, "message": "sample", "report_pdf": "sample", "report_xml": "sample" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/mobile-to-udyam-v1": { "post": { "operationId": "mobileToUdyamV1", "tags": [ "kyb" ], "summary": "Mobile to Udyam Lookup", "description": "Find Udyam (MSME) registrations linked to a mobile number.\n\nSLOW BY DESIGN — SET A LONG TIMEOUT. This endpoint takes 24-27 seconds against a source that is currently degraded; measured 24.5s and 26.3s on consecutive live calls. Set your client timeout to at least 45 seconds. A 30-second client timeout WILL fail intermittently on this product even though the call succeeds on our side, and you will be charged for a result you never see. Every other product in the catalogue returns in a few seconds; this one is the exception.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "10-digit mobile number" } } }, "example": { "mobile": "9876543210" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mobile": { "type": "string" }, "udyams": { "type": "array" }, "verified": { "type": "boolean" } } }, "example": { "mobile": "9876543210", "udyams": [], "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/name-match": { "post": { "operationId": "nameMatch", "tags": [ "kyc" ], "summary": "Name Match", "description": "Score how likely two spellings of a name belong to the same person, from 0 to 100. Built for Indian KYC records: it ignores case, punctuation, titles (Mr, Smt, Dr, Shri) and word order, understands initials (R Kumar / Ravi Kumar), joined names (Vijaykumar / Vijay Kumar), common abbreviations (Mohd / Mohammed, Kr / Kumar) and spelling variants (Preeti / Priti, Rafiq / Rafik). A missing middle name costs a little; a different first name costs a lot. Returns the score, a match flag at your threshold (default 80) and the kind of match.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name1", "name2" ], "properties": { "name1": { "type": "string", "maxLength": 200, "description": "First name to compare, e.g. from the PAN record." }, "name2": { "type": "string", "maxLength": 200, "description": "Second name, e.g. from the bank account." }, "threshold": { "type": "number", "minimum": 0, "maximum": 100, "description": "Optional. Score at or above which match is true. Default 80." } }, "additionalProperties": false }, "example": { "name1": "MOHD RAFIQ KHAN", "name2": "Mohammed Rafik Khan" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "score": { "type": "integer" }, "match": { "type": "boolean" }, "threshold": { "type": "number" }, "match_type": { "type": "string", "enum": [ "exact", "reordered", "spacing", "initials", "partial", "fuzzy", "mismatch" ] }, "name1_normalized": { "type": "string" }, "name2_normalized": { "type": "string" } } }, "example": { "score": 98, "match": true, "threshold": 80, "match_type": "fuzzy", "name1_normalized": "MOHAMMED RAFIQ KHAN", "name2_normalized": "MOHAMMED RAFIK KHAN" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/id-format-validate-v1": { "post": { "operationId": "idFormatValidateV1", "tags": [ "kyc" ], "summary": "ID Format Validator", "description": "Check that Indian identifiers are well-formed before you pay for a lookup: PAN, GSTIN (with check character), Aadhaar (Verhoeff check digit), Aadhaar VID, IFSC, mobile, email, UPI ID, CIN, LLPIN, DIN, TAN, Udyam, Voter ID, passport, driving licence and vehicle registration. Send any combination in one call. Each comes back valid or not, with the reason and what its structure tells you (PAN holder type, GSTIN state and embedded PAN, CIN company type and year). This checks format only, not whether the number exists. A full Aadhaar number is never echoed back.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "pan": { "type": "string" }, "gstin": { "type": "string" }, "aadhaar": { "type": "string" }, "vid": { "type": "string" }, "ifsc": { "type": "string" }, "mobile": { "type": "string" }, "email": { "type": "string" }, "upi": { "type": "string" }, "cin": { "type": "string" }, "llpin": { "type": "string" }, "din": { "type": "string" }, "tan": { "type": "string" }, "udyam": { "type": "string" }, "voter_id": { "type": "string" }, "passport": { "type": "string" }, "dl": { "type": "string" }, "vehicle_rc": { "type": "string" } }, "additionalProperties": false }, "example": { "pan": "ABCPE1234F", "gstin": "27AAPFU0939F1ZV", "aadhaar": "499118665246", "mobile": "+91 98765 43210" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "all_valid": { "type": "boolean" }, "results": { "type": "object", "description": "One entry per field sent: {valid, normalized, reason?, details?}." } } }, "example": { "all_valid": true, "results": { "pan": { "valid": true, "normalized": "ABCPE1234F", "details": { "holder_type": "Individual", "holder_type_code": "P", "name_initial": "E" } }, "gstin": { "valid": true, "normalized": "27AAPFU0939F1ZV", "details": { "state_code": "27", "state": "Maharashtra", "pan": "AAPFU0939F", "pan_format_valid": true, "holder_type": "Firm / LLP", "registration_number": "1" } }, "aadhaar": { "valid": true, "normalized": "XXXXXXXX5246", "details": { "last4": "5246" } }, "mobile": { "valid": true, "normalized": "9876543210", "details": { "e164": "+919876543210" } } } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pincode-lookup-v1": { "post": { "operationId": "pincodeLookupV1", "tags": [ "kyc" ], "summary": "Pincode Lookup", "description": "Look up an Indian pincode and get its district, state, postal division and circle, every post office it covers (head, sub and branch offices, with delivery status) and map coordinates where India Post publishes them. Data: India Post's All India Pincode Directory. Use it to auto-fill addresses and to check that a customer's pincode matches their stated city and state. A pincode India Post does not list returns 404 and is not charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pincode" ], "properties": { "pincode": { "type": "string", "pattern": "^[1-9][0-9]{5}$", "description": "6-digit Indian pincode." } }, "additionalProperties": false }, "example": { "pincode": "302001" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pincode": { "type": "string" }, "found": { "type": "boolean" }, "district": { "type": "string" }, "state": { "type": "string" }, "division": { "type": "string" }, "region": { "type": "string" }, "circle": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "offices": { "type": "array" }, "meta": { "type": "object" } } }, "example": { "pincode": "302001", "found": true, "district": "Jaipur", "state": "Rajasthan", "division": "Jaipur City Division", "region": null, "circle": "Rajasthan Circle", "latitude": 26.91753, "longitude": 75.80367, "offices": [ { "name": "Jaipur G.P.O.", "type": "Head Office", "delivery": true, "latitude": 26.91753, "longitude": 75.80367 }, { "name": "C.P.M.G S.O", "type": "Sub Office", "delivery": false, "latitude": 26.91397, "longitude": 75.79967 }, { "name": "Chandpole Bazar S.O", "type": "Sub Office", "delivery": false, "latitude": 26.92628, "longitude": 75.80981 } ], "meta": { "source": "India Post — All India Pincode Directory (data.gov.in, GODL-India)", "data_as_of": "2026-10-17" } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "India Post lists no post office for this pincode. Not charged; do not retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/digipin-v1": { "post": { "operationId": "digipinV1", "tags": [ "kyc" ], "summary": "DIGIPIN Lookup", "description": "Convert between map coordinates and India Post's DIGIPIN, the 10-character code for a roughly 4m x 4m square anywhere in India. Send latitude and longitude to get the DIGIPIN, or a DIGIPIN to get its location. Either way you also get the nearest post office and its pincode, so a captured GPS point becomes a postal address hint. Uses India Post's official open algorithm. Nearest office is approximate: it is the closest office India Post publishes coordinates for, not the postal boundary.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "digipin": { "type": "string", "description": "10-character DIGIPIN, e.g. 4T396F42L7 (dashes optional)." }, "latitude": { "type": "number", "minimum": 2.5, "maximum": 38.5 }, "longitude": { "type": "number", "minimum": 63.5, "maximum": 99.5 } }, "additionalProperties": false }, "example": { "latitude": 26.9124, "longitude": 75.7873 } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "digipin": { "type": "string" }, "digipin_formatted": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "bounds": { "type": "object" }, "nearest_post_office": { "type": "object" } } }, "example": { "digipin": "33C635JK43", "digipin_formatted": "33C-635-JK43", "latitude": 26.9124, "longitude": 75.7873, "bounds": { "min_latitude": 26.912376, "max_latitude": 26.912411, "min_longitude": 75.787281, "max_longitude": 75.787315 }, "nearest_post_office": { "name": "P.W.D.Office S.O", "type": "Sub Office", "pincode": "302006", "district": "Jaipur", "state": "Rajasthan", "distance_km": 0.35 } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/lei-lookup-v1": { "post": { "operationId": "leiLookupV1", "tags": [ "kyc" ], "summary": "LEI Lookup", "description": "Look up a Legal Entity Identifier (LEI) in the Global LEI Index, by LEI, by company registration number (CIN or LLPIN) or by company name. Returns the legal name, registration number, legal and head-office address, entity status, and whether the LEI is currently valid for regulatory use (ISSUED) or has lapsed. RBI requires an LEI for large-value payments and for borrowers above set exposure limits. Name searches return up to 10 entities ranked by how closely the name matches.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lei": { "type": "string", "description": "20-character LEI." }, "registration_number": { "type": "string", "description": "CIN or LLPIN (for Indian entities)." }, "name": { "type": "string", "minLength": 3, "description": "Company legal name; Ltd / Pvt suffixes are optional." }, "country": { "type": "string", "description": "2-letter ISO country for registration-number and name searches. Default IN." } }, "additionalProperties": false }, "example": { "lei": "5493003UOETFYRONLG31" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "found": { "type": "boolean" }, "lei": { "type": "string" }, "legal_name": { "type": "string" }, "registration_number": { "type": "string" }, "entity_status": { "type": "string" }, "lei_status": { "type": "string" }, "lei_valid_for_use": { "type": "boolean" }, "next_renewal_on": { "type": "string" }, "legal_address": { "type": "object" }, "headquarters_address": { "type": "object" }, "count": { "type": "integer" }, "results": { "type": "array" } } }, "example": { "found": true, "lei": "5493003UOETFYRONLG31", "legal_name": "RELIANCE INDUSTRIES LIMITED", "other_names": [], "registration_number": "L17110MH1973PLC019786", "jurisdiction": "IN", "category": "GENERAL", "entity_status": "ACTIVE", "incorporated_on": "1973-05-08", "legal_address": { "lines": [ "3 RD FLOORMAKER CHAMBER IV 222 NARIMAN POINT" ], "city": "MUMBAI", "region": "IN-MH", "postal_code": "400021", "country": "IN" }, "headquarters_address": { "lines": [ "3 RD FLOORMAKER CHAMBER IV 222 NARIMAN POINT" ], "city": "MUMBAI", "region": "IN-MH", "postal_code": "400021", "country": "IN" }, "lei_status": "ISSUED", "lei_valid_for_use": true, "first_registered_on": "2014-01-01", "last_updated_on": "2025-10-06", "next_renewal_on": "2026-11-21", "corroboration": "FULLY_CORROBORATED" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/email-check-v1": { "post": { "operationId": "emailCheckV1", "tags": [ "kyc" ], "summary": "Email Check", "description": "Check an email address without sending it anything: is the format valid, does the domain accept mail (MX record), is it a throwaway / disposable address (about 9,800 known domains), a free provider like Gmail, or a role address like info@ or sales@. deliverable is true when the domain can receive mail and nothing marks the address as junk. It does not confirm that the individual mailbox exists.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "maxLength": 254 } }, "additionalProperties": false }, "example": { "email": "ravi.kumar@outlook.com" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "valid_syntax": { "type": "boolean" }, "domain": { "type": "string" }, "mx_found": { "type": "boolean" }, "mx_records": { "type": "array" }, "disposable": { "type": "boolean" }, "free_provider": { "type": "boolean" }, "role_address": { "type": "boolean" }, "deliverable": { "type": "boolean" } } }, "example": { "email": "ravi.kumar@outlook.com", "valid_syntax": true, "domain": "outlook.com", "mx_found": true, "mx_records": [ "outlook-com.olc.protection.outlook.com" ], "disposable": false, "free_provider": true, "role_address": false, "deliverable": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/hsn-sac-lookup-v1": { "post": { "operationId": "hsnSacLookupV1", "tags": [ "kyc" ], "summary": "HSN / SAC Code Lookup", "description": "Find the right HSN code for goods or SAC code for services, or look up what a code means. Send code to get its description, its place in the tariff (chapter, heading, sub-heading) and the codes under it. Send query to search by plain words: everyday terms like laptop, saree or t-shirt are mapped to the official tariff wording. Data: the GST portal's HSN/SAC master. This returns codes and descriptions only, not GST rates.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "HSN (2, 4, 6 or 8 digits) or SAC (starts 99)." }, "query": { "type": "string", "minLength": 2, "description": "Words to search, e.g. cotton t-shirt." }, "type": { "type": "string", "enum": [ "HSN", "SAC" ], "description": "Optional. Limit a search to goods or services." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Optional. Default 20." } }, "additionalProperties": false }, "example": { "query": "laptop", "limit": 2 } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "type": { "type": "string" }, "found": { "type": "boolean" }, "level": { "type": "string" }, "description": { "type": "string" }, "full_description": { "type": "string" }, "hierarchy": { "type": "array" }, "children": { "type": "array" }, "results": { "type": "array" }, "meta": { "type": "object" } } }, "example": { "query": "laptop", "count": 2, "total_matches": 3, "results": [ { "code": "847130", "type": "HSN", "description": "Portable automatic data processing machines, weighing not more than 10 kg, consisting of atleast a central processing unit, a keyboard and a display:", "full_description": "Portable automatic data processing machines, weighing not more than 10 kg, consisting of atleast a central processing unit, a keyboard and a display:", "relevance": 5.6 }, { "code": "84713090", "type": "HSN", "description": "Other", "full_description": "Automatic data processing machines and units there of , magnetic or optical readers, machines for transcribing data on to data media in coded form and machines for processing such data, not elsewhere specified or included — Portable automatic data processing machines, weighing not more than 10 kg, consisting of atleast a central processing unit, a keyboard and a display: — Other", "relevance": 3.8 } ], "meta": { "source": "GSTN HSN/SAC master (tutorial.gst.gov.in/downloads/HSN_SAC.xlsx)", "data_as_of": "2026-10-18" } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/bank-statement-to-excel-v1": { "post": { "operationId": "bankStatementToExcelV1", "tags": [ "ai" ], "summary": "Bank Statement to Excel", "description": "Convert a bank-statement PDF into a clean Excel workbook (or CSV, or JSON rows): one row per transaction with date, narration, reference, debit, credit and balance, plus a summary sheet with the account, period, opening and closing balance and totals. The reading is checked against the statement's own running balance, so the rows add up. Works across Indian banks without per-bank templates. Digital PDFs from net banking only, not scans. The file comes back base64-encoded with its file name.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pdf_base64" ], "properties": { "pdf_base64": { "type": "string", "description": "Base64-encoded bank-statement PDF (digital, not a scan). Max 15 MB." }, "password": { "type": "string", "description": "PDF password, if the statement is locked." }, "format": { "type": "string", "enum": [ "xlsx", "csv", "json" ], "description": "Default xlsx." } }, "additionalProperties": false }, "example": { "pdf_base64": "", "format": "xlsx" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object" }, "period": { "type": "object" }, "opening_balance": { "type": "number" }, "closing_balance": { "type": "number" }, "currency": { "type": "string" }, "transaction_count": { "type": "integer" }, "format": { "type": "string" }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "file_base64": { "type": "string" }, "transactions": { "type": "array" }, "meta": { "type": "object" } } }, "example": { "account": { "account_holder": null, "account_number": "XXXX7890", "bank": null, "ifsc": "SAMP0001234", "account_type": null }, "period": { "from": "2026-04-01", "to": "2026-04-30" }, "opening_balance": 10000, "closing_balance": 34620, "currency": "INR", "transaction_count": 5, "format": "xlsx", "meta": { "engine": "apisathi-statement-export-v1", "pages": 1 }, "file_name": "statement_20260401_20260430.xlsx", "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "file_base64": "UEsDBAoAAAAIAK8aUl3qc8NaXAEAAHgFAAATAAAA…" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/sanctions-screening-v1": { "post": { "operationId": "sanctionsScreeningV1", "tags": [ "kyc" ], "summary": "Sanctions Screening (UN, OFAC, EU)", "description": "Screen a person or company name against the UN Security Council Consolidated List, the US OFAC SDN list and the EU Consolidated Financial Sanctions List in one call. Lists are refreshed from the official sources every 6 hours. Matching understands spelling variants, initials, word order and aliases. Pass dob to rank hits with the same birth year first and to set aside same-name hits with a different birth year. result is possible_match when at least one hit is not ruled out by date of birth: send those for manual review. A hit is never proof on its own.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 200 }, "type": { "type": "string", "enum": [ "individual", "entity" ], "description": "Optional. Default both." }, "dob": { "type": "string", "description": "Optional. Date of birth or year, e.g. 1975-05-12." }, "threshold": { "type": "number", "minimum": 50, "maximum": 100, "description": "Optional. Minimum name-match score, default 85." } }, "additionalProperties": false }, "example": { "name": "Hafiz Muhammad Saeed", "dob": "1950-06-05" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "result": { "type": "string", "enum": [ "clear", "possible_match" ] }, "hit_count": { "type": "integer" }, "hits": { "type": "array" }, "threshold": { "type": "number" }, "lists": { "type": "object" }, "lists_as_of": { "type": "string" } } }, "example": { "name": "Hafiz Muhammad Saeed", "result": "possible_match", "hit_count": 2, "hits": [ { "source": "UN", "reference": "QDi.263", "type": "individual", "listed_name": "HAFIZ MUHAMMAD SAEED", "matched_name": "HAFIZ MUHAMMAD SAEED", "score": 100, "dob_match": true, "dob": [ "1950-06-05" ], "nationality": [ "Pakistan" ], "programme": "Al-Qaida", "listed_on": "2008-12-10" }, { "source": "EU", "reference": "5419", "type": "individual", "listed_name": "Hafiz Muhammad Saeed", "matched_name": "Hafiz Muhammad Saeed", "score": 100, "dob_match": true, "dob": [ "1950-06-05" ], "nationality": [], "programme": "TAQA", "listed_on": "2008-12-10" } ], "threshold": 85, "lists": { "UN": { "generated": "2026-10-17T23:00:01.054Z", "count": 1010 }, "OFAC": { "generated": null, "count": 17556 }, "EU": { "generated": "15/10/2026", "count": 6234 } }, "lists_as_of": "2026-10-18T03:00:00.000Z" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-business-profile-v1": { "post": { "operationId": "panBusinessProfileV1", "tags": [ "kyc" ], "summary": "PAN Business Profile", "description": "A complete business profile from one PAN, in one call: the PAN holder (name, type, status, address), every GST registration under the PAN with full details (status, constitution, turnover slab, nature of business, latest returns) for the active ones, the company's MCA record (CIN, status, capital, industry, registered address, active directors, registered charges), director identification for individual PANs, and the Legal Entity Identifier (LEI). Pass include_report: true to also get a ready-to-share PDF report. Company and LLP PANs get the MCA record; individual PANs get their director record if they hold a DIN. Parts that a registry has no record of come back empty rather than failing the call. Charged once per call, only when the PAN is found; a PAN with no record anywhere returns 404 and is not charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Za-z]{5}[0-9]{4}[A-Za-z]$", "description": "10-character PAN of the business or individual." }, "include_report": { "type": "boolean", "description": "Optional. Also return a PDF report (base64) in report.file_base64." } }, "additionalProperties": false }, "example": { "pan": "AAACR5055K", "include_report": false } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pan": { "type": "string" }, "found": { "type": "boolean" }, "holder": { "type": "object", "description": "Name, PAN type and status, allotment date, address (date of birth and gender only for individuals)." }, "gst": { "type": "object", "description": "count, active_count, registrations[] (gstin, state, status) and details[] for up to 3 active GSTINs." }, "company": { "type": "object", "description": "MCA record for company/LLP PANs: CIN, status, capital, industry, addresses, directors, charges." }, "director": { "type": "object", "description": "DIN record for individual PANs that hold one." }, "lei": { "type": "object" }, "sources": { "type": "array", "description": "Which parts were found / not found." }, "report": { "type": "object", "description": "Present when include_report is true: file_name, content_type, file_base64." }, "meta": { "type": "object" } } }, "example": { "pan": "AAACR5055K", "found": true, "holder": { "name": "RELIANCE INDUSTRIES LIMITED", "pan_type": "Company", "pan_status": "VALID", "allotment_date": "1975-03-01", "aadhaar_linked": null, "address": { "line": "MAKER CHAMBERS IV, NARIMAN POINT", "city": "MUMBAI", "state": "MAHARASHTRA", "pincode": "400021" } }, "gst": { "count": 3, "active_count": 2, "registrations": [ { "gstin": "27AAACR5055K1Z7", "state": "Maharashtra", "state_code": "27", "status": "Active" }, { "gstin": "24AAACR5055K1Z9", "state": "Gujarat", "state_code": "24", "status": "Active" }, { "gstin": "07AAACR5055K1Z3", "state": "Delhi", "state_code": "07", "status": "Cancelled" } ], "details": [ { "gstin": "27AAACR5055K1Z7", "legal_name": "RELIANCE INDUSTRIES LIMITED", "trade_name": "RELIANCE INDUSTRIES LIMITED", "status": "Active", "constitution": "Public Limited Company", "taxpayer_type": "Regular", "registration_date": "01/07/2017", "cancellation_date": null, "aggregate_turnover": "Slab: Rs. 500 Cr. and above", "aggregate_turnover_fy": "2025-2026", "nature_of_business": [ "Factory / Manufacturing", "Wholesale Business" ], "einvoice_status": "Yes", "principal_address": "MAKER CHAMBERS IV, NARIMAN POINT, MUMBAI, MAHARASHTRA, 400021", "last_filing": "GSTR3B September 2026-2027 filed 20/10/2026", "recent_filings": [ { "return_type": "GSTR3B", "period": "September", "fy": "2026-2027", "filed_on": "20/10/2026", "status": "Filed" } ] } ] }, "company": { "cin": "L17110MH1973PLC019786", "name": "RELIANCE INDUSTRIES LIMITED", "status": "Active", "type": "Company limited by shares", "category": "Company limited by Shares", "sub_category": "Non-govt company", "class": "Public", "incorporation_date": "1973-05-08", "roc": "RoC-Mumbai", "authorised_capital": "150000000000", "paid_up_capital": "135320000000", "listed": "Listed", "last_agm": "2026-08-28", "balance_sheet_date": "2026-03-31", "active_compliance": "ACTIVE compliant", "industry": "Manufacture of refined petroleum products", "registered_address": "3RD FLOOR, MAKER CHAMBERS IV, 222 NARIMAN POINT, MUMBAI 400021", "email": "investor.relations@example.com", "addresses": [ { "type": "Registered Address", "address": "3RD FLOOR, MAKER CHAMBERS IV, 222 NARIMAN POINT, MUMBAI, Maharashtra, 400021", "active": true } ], "directors": [ { "name": "MUKESH DHIRUBHAI AMBANI", "din": "00001695", "role": "Managing Director", "appointed": "1977-01-11" } ], "charges": [ { "holder": "STATE BANK OF INDIA", "amount": "10000000000", "created": "2020-03-12", "satisfied": null, "status": "OPEN" } ] }, "director": null, "lei": { "lei": "5493003UOETFYRONLG31", "legal_name": "RELIANCE INDUSTRIES LIMITED", "status": "ISSUED", "valid_for_use": true, "next_renewal": "2027-05-01" }, "sources": [ { "source": "pan", "status": "found" }, { "source": "gst_by_pan", "status": "found" }, { "source": "pan_to_cin", "status": "found" }, { "source": "company_registry", "status": "found" }, { "source": "gst_details", "status": "found" }, { "source": "lei", "status": "found" } ], "meta": { "engine": "apisathi-business-profile-v1", "generated_at": "2026-10-22T05:00:00.000Z" } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "No record of this PAN in any source. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-aadhaar-link": { "post": { "operationId": "panAadhaarLink", "tags": [ "kyc" ], "summary": "PAN–Aadhaar Link Status", "description": "Whether a PAN is linked to the given Aadhaar. Returns a definitive answer either way — `linked: true` or `linked: false` — and both are billed, because both are answers. Individual PANs only: a company PAN has no Aadhaar and is rejected with a clear message (422, not charged).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan", "aadhaar" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$" }, "aadhaar": { "type": "string", "pattern": "^[0-9]{12}$", "description": "12-digit Aadhaar number." } }, "additionalProperties": false }, "example": { "pan": "ABCPD1234E", "aadhaar": "999912341234" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "true when linked." }, "linked": { "type": "boolean" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Source's status code, e.g. LINK-001." } } }, "example": { "verified": true, "linked": true, "message": "PAN is linked to the Aadhaar", "code": "LINK-001" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-basic-v1": { "post": { "operationId": "panBasicV1", "tags": [ "kyc" ], "summary": "PAN Basic Verification", "description": "Confirms a PAN exists and is active, with the registered name. The cheapest PAN check — use it when you only need existence and status. Use PAN Verification for date of birth and holder category, or PAN Details Plus for the full profile.\n\nBilled on success only; a PAN with no record is not charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$", "description": "10-character PAN, upper case." } }, "additionalProperties": false }, "example": { "pan": "ABCPD1234E" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "pan": { "type": "string" }, "name": { "type": "string", "description": "Name as registered with the Income Tax Department." }, "status": { "type": "string", "description": "Active / Inactive / Deleted." }, "aadhaar_seeding_status": { "type": "string" } } }, "example": { "verified": true, "pan": "ABCPD1234E", "name": "RAHUL VERMA", "status": "Active", "aadhaar_seeding_status": "Y" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-details-plus": { "post": { "operationId": "panDetailsPlus", "tags": [ "kyc" ], "summary": "PAN Details Plus", "description": "The full PAN profile in one call: name parts, date of birth, gender, PAN type and status, allotment date, Aadhaar-linked flag with the masked Aadhaar, registered address, email and mobile on record, and whether the holder is a company director, salaried, or a sole proprietor.\n\nBuilt for underwriting: one call answers most of a KYC form. For a company PAN, `dob` is the date of incorporation and `signatory_details` lists the authorised signatories.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$" } }, "additionalProperties": false }, "example": { "pan": "ABCPD1234E" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "pan": { "type": "string" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "middle_name": { "type": "string" }, "last_name": { "type": "string" }, "dob": { "type": "string", "description": "DD/MM/YYYY. Incorporation date for non-individual PANs." }, "gender": { "type": "string" }, "pan_type": { "type": "string", "description": "Individual, Company, Firm, HUF, Trust…" }, "pan_status": { "type": "string" }, "pan_allotment_date": { "type": "string" }, "aadhaar_linked": { "type": "boolean" }, "masked_aadhaar": { "type": "string" }, "address": { "type": "object" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "is_director": { "type": "boolean" }, "is_salaried": { "type": "boolean" }, "is_sole_proprietor": { "type": "boolean" }, "signatory_details": { "type": "array" } } }, "example": { "verified": true, "pan": "ABCPD1234E", "name": "RAHUL VERMA", "first_name": "RAHUL", "last_name": "VERMA", "dob": "12/04/1991", "gender": "M", "pan_type": "Individual", "pan_status": "Active", "aadhaar_linked": true, "masked_aadhaar": "XXXXXXXX1234", "address": { "city": "Jaipur", "state": "Rajasthan", "pincode": "302017" }, "is_director": false, "is_salaried": true, "is_sole_proprietor": false } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-verification-v1": { "post": { "operationId": "panVerificationV1", "tags": [ "kyc" ], "summary": "PAN Verification", "description": "Verify a PAN against the government source. Returns verified flag, name, DOB, gender, Aadhaar-link flag, category (holder type) and address.\n\nSend a REAL, well-formed PAN. A structurally invalid or non-existent PAN (e.g. a placeholder like \"ABCDE1234F\" — the 4th letter must be a valid holder-type code such as P for individual) returns 422 INVALID_INPUT, not a result. Billed on SUCCESS only — invalid/no-record lookups are NOT charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$" } }, "additionalProperties": false }, "example": { "pan": "ABCDE1234F" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dob": { "type": "string", "format": "date" }, "name": { "type": "string" }, "category": { "type": "string" }, "verified": { "type": "boolean" }, "aadhaar_linked": { "type": "boolean", "description": "Whether an Aadhaar is seeded against this PAN." }, "aadhaar_number": { "type": "string", "description": "The linked Aadhaar, MASKED at source as 72XXXXXXXX67 — first two and last two digits only. Enough to match against an Aadhaar you already hold; it is never returned unmasked." } } }, "example": { "dob": "1990-01-15", "name": "Rohit Sharma", "category": "sample", "verified": true, "aadhaar_linked": true, "aadhaar_number": "72XXXXXXXX67" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-to-cin-v1": { "post": { "operationId": "panToCinV1", "tags": [ "kyb" ], "summary": "PAN to CIN", "description": "Resolve the company CIN and basics (name, status, incorporation date) linked to a COMPANY PAN. Requires a company/entity PAN — the 4th letter must be C, F, H, A, T etc., NOT an individual PAN (P). An individual or unrecognized PAN returns 422 INVALID_INPUT (a company has no CIN). Billed on success only.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "description": "10-character PAN" } } }, "example": { "pan": "ABCDE1234F" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cin": { "type": "string" }, "verified": { "type": "boolean" }, "company_name": { "type": "string" }, "company_status": { "type": "string" }, "date_of_incorporation": { "type": "string" } } }, "example": { "cin": "U72900KA2018PTC114387", "verified": true, "company_name": "Rohit Sharma", "company_status": "sample", "date_of_incorporation": "sample" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-to-din-v1": { "post": { "operationId": "panToDinV1", "tags": [ "kyb" ], "summary": "PAN to DIN", "description": "Resolve the Director Identification Number (DIN) linked to a PAN.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "description": "10-character PAN" } } }, "example": { "pan": "ABCDE1234F" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "din": { "type": "string" }, "verified": { "type": "boolean" } } }, "example": { "din": "00001095", "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-to-father-name": { "post": { "operationId": "panToFatherName", "tags": [ "kyc" ], "summary": "PAN to Father Name", "description": "Returns the father's name registered against an individual PAN, masked as the source provides it. Used for name-match and KYC form pre-fill. Individual PANs only (4th character P).", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{3}P[A-Z][0-9]{4}[A-Z]$" } }, "additionalProperties": false }, "example": { "pan": "ABCPD1234E" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "pan": { "type": "string" }, "father_name": { "type": "string", "description": "Masked, e.g. SXXXXH VXXXA." } } }, "example": { "verified": true, "pan": "ABCPD1234E", "father_name": "SXXXXH VXXXA" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/pan-to-masked-aadhaar": { "post": { "operationId": "panToMaskedAadhaar", "tags": [ "kyc" ], "summary": "PAN to Masked Aadhaar", "description": "Returns whether a PAN is linked to an Aadhaar and the masked Aadhaar number seeded against it (first 2 and last 2 digits visible, e.g. 12XXXXXXXX34), without the holder entering Aadhaar or an OTP.\n\nThe full Aadhaar number is never returned: under the Aadhaar Act only the holder may share it. To check a full number your customer gives you, use pan-aadhaar-link (verifies it, never reveals it). For verified Aadhaar details with consent, use DigiLocker (aadhaar-digilocker-init-v1 / aadhaar-digilocker-fetch-v1).\n\nIndividual PANs only; a company PAN has no Aadhaar.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pan" ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$", "description": "Individual PAN" } }, "additionalProperties": false }, "example": { "pan": "ABCPE1234F" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "linked": { "type": "boolean", "description": "true if the PAN is linked to an Aadhaar" }, "masked_aadhaar": { "type": "string", "description": "First 2 and last 2 digits visible, e.g. 12XXXXXXXX34. null when not linked." }, "verified": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "linked": true, "masked_aadhaar": "12XXXXXXXX34", "verified": true, "message": null } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/passport-validation": { "post": { "operationId": "passportValidation", "tags": [ "kyc" ], "summary": "Passport Verification", "description": "Verifies a passport application against the Passport Seva record using the file number and date of birth: given name, surname, masked passport number, application type and key dates. The file number is on the application receipt (e.g. GZ1012345678912); date of birth as DD/MM/YYYY. No record returns 404 and is not charged.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_number", "dob" ], "properties": { "file_number": { "type": "string", "minLength": 10, "maxLength": 20 }, "dob": { "type": "string", "pattern": "^[0-3][0-9]/[01][0-9]/[12][0-9]{3}$", "description": "DD/MM/YYYY" } }, "additionalProperties": false }, "example": { "file_number": "GZ1012345678912", "dob": "12/04/1991" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "file_number": { "type": "string" }, "passport_number": { "type": "string", "description": "Masked." }, "given_name": { "type": "string" }, "surname": { "type": "string" }, "dob": { "type": "string" }, "application_type": { "type": "string" }, "application_date": { "type": "string" }, "date_of_dispatch": { "type": "string" } } }, "example": { "verified": true, "file_number": "GZ1012345678912", "passport_number": "Pxxxxx45", "given_name": "RAHUL", "surname": "VERMA", "dob": "12/04/1991", "application_type": "Normal", "application_date": "09/09/2016", "date_of_dispatch": "31/10/2016" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "No record for those details. Definitive; not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/rc-challan": { "post": { "operationId": "rcChallan", "tags": [ "vehicle" ], "summary": "RC e-Challan Details", "description": "Pending traffic e-Challan details for a vehicle registration (RC) number, sourced from VAHAN/Parivahan. Returns the list of challans and a total count; a vehicle with no pending challans returns echallan_count 0.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rc_number" ], "properties": { "rc_number": { "type": "string", "description": "Vehicle registration number, e.g. MH14GH2255", "pattern": "^[A-Z]{2}[0-9]{1,2}[A-Z]{0,3}[0-9]{1,4}$" } }, "additionalProperties": false }, "example": { "rc_number": "MH14GH2255" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rc_number": { "type": "string" }, "result_code": { "type": "integer", "description": "101 = challans found; 103 = no pending challans (clean vehicle)." }, "message": { "type": "string" }, "echallan_count": { "type": "integer", "description": "Number of pending challans — 0 for a clean vehicle." }, "challans": { "type": "array", "description": "One entry per pending challan.", "items": { "type": "object", "properties": { "challan_no": { "type": "string" }, "challan_date": { "type": "string" }, "amount": { "type": "string" }, "challan_status": { "type": "string" }, "offence": { "type": "string" }, "state": { "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "example": { "rc_number": "MH14GH2255", "result_code": 101, "message": "success", "echallan_count": 1, "challans": [ { "challan_no": "MH00123456789012", "challan_date": "2026-03-14 10:22:00", "amount": "500", "challan_status": "Pending", "offence": "Over Speeding", "state": "Maharashtra" } ] } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/sms-send-v1": { "post": { "operationId": "smsSendV1", "tags": [ "communication" ], "summary": "SMS Transactional", "description": "Send a loan-eligibility / credit-rating CONSENT OTP by SMS on a DLT-approved template. Pass the OTP you generated as `variables.otp` — the message wording and DLT template are fixed server-side (you do NOT choose the text). This is one of a family of purpose-specific SMS APIs — to send a different message, call the API for that message type (e.g. `sms-credit-consent-v1` for an Experian credit-report consent OTP). Charged per SMS on success.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "variables" ], "properties": { "to": { "type": "string", "pattern": "^\\+?91?\\d{10}$", "description": "Recipient mobile. Any Indian format is accepted and normalised server-side: +919876543210, 919876543210, 9876543210, and separators such as spaces or hyphens." }, "variables": { "type": "object", "required": [ "otp" ], "properties": { "otp": { "type": "string", "description": "The OTP value to send" } }, "description": "Template variables. This template takes a single `otp`." } }, "additionalProperties": false }, "example": { "to": "+919876543210", "variables": { "otp": "482913" } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" } } }, "example": { "sent": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/sms-credit-consent-v1": { "post": { "operationId": "smsCreditConsentV1", "tags": [ "communication" ], "summary": "Credit Consent OTP (SMS)", "description": "Send a borrower a credit-report (Experian) CONSENT OTP by SMS on a DLT-approved template. Use this to capture consent before a `credit-report-v1` pull: send the OTP here, have the borrower read it back, then pass that same OTP to `credit-report-v1`. The message wording and DLT template are fixed server-side; you only supply the OTP value. The OTP is stated valid for 10 minutes in the message. Charged per SMS on success.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "variables" ], "properties": { "to": { "type": "string", "pattern": "^\\+?91?\\d{10}$", "description": "Borrower mobile. Any Indian format is accepted and normalised server-side: +919876543210, 919876543210, 9876543210, and separators such as spaces or hyphens." }, "variables": { "type": "object", "required": [ "otp" ], "properties": { "otp": { "type": "string", "description": "The consent OTP value to send" } }, "description": "Template variables. This template takes a single `otp`." } }, "additionalProperties": false }, "example": { "to": "+919876543210", "variables": { "otp": "534216" } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" } } }, "example": { "sent": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/skip-tracing": { "post": { "operationId": "skipTracing", "tags": [ "credit" ], "summary": "Skip Tracing", "description": "Locate and profile a borrower from a PAN or mobile number: current and historical addresses, alternate mobiles and emails, employment and business profile, bank and UPI presence, social footprint — each section with its own confidence and source status.\n\nBuilt for collections and field-verification teams. Supply `pan` or `mobile` (at least one); `name` improves matching. Sections the sources cannot resolve come back empty with `metadata.
.status` explaining why, and the call is still billed — it is a search, not a lookup.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "required": [ "pan" ] }, { "required": [ "mobile" ] } ], "properties": { "pan": { "type": "string", "pattern": "^[A-Z]{5}[0-9]{4}[A-Z]$" }, "mobile": { "type": "string", "pattern": "^[6-9][0-9]{9}$" }, "name": { "type": "string", "maxLength": 120 } }, "additionalProperties": false }, "example": { "pan": "ABCPD1234E", "name": "RAHUL VERMA" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "profile": { "type": "object", "description": "Name, DOB, gender, father name where resolvable." }, "contactability": { "type": "object", "description": "mobile_number, alternate_mobiles[], emails[]." }, "addresses": { "type": "array", "description": "Each with address, pincode, source and last-seen date." }, "pan_profile": { "type": "object" }, "employment_profile": { "type": "object" }, "business_profile": { "type": "object" }, "banking_profile": { "type": "object", "description": "bank_accounts[], upi_accounts[] — presence, not balances." }, "social_profile": { "type": "object" }, "insights": { "type": "object" }, "metadata": { "type": "object", "description": "Per-section status and source." } } }, "example": { "verified": true, "profile": { "name": "RAHUL VERMA", "dob": "1991-04-12", "gender": "M" }, "contactability": { "mobile_number": "98XXXXXX10", "alternate_mobiles": [ "97XXXXXX21" ], "emails": [ "r****@gmail.com" ] }, "addresses": [ { "address": "14, Shanti Niketan, Malviya Nagar, Jaipur", "pincode": "302017", "source": "bureau", "last_seen": "2026-06" } ], "pan_profile": { "pan": "ABCPD1234E", "pan_status": "ACTIVE" }, "employment_profile": { "recent_employer_name": "ACME INFOTECH PRIVATE LIMITED", "source": "epfo" }, "insights": { "total_addresses": 3, "total_unique_addresses": 2 } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/tan-lookup-v1": { "post": { "operationId": "tanLookupV1", "tags": [ "kyb" ], "summary": "TAN Lookup", "description": "Look up TANs registered against a company name with match scores.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_name" ], "properties": { "company_name": { "type": "string", "description": "Legal or registered company name" }, "output_count": { "type": "integer", "description": "Optional max number of results" } } }, "example": { "company_name": "Rohit Sharma", "output_count": 10 } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "matches": { "type": "array" }, "verified": { "type": "boolean" } } }, "example": { "matches": [], "verified": true } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/tan-to-company-v1": { "post": { "operationId": "tanToCompanyV1", "tags": [ "kyb" ], "summary": "TAN to Company", "description": "Validate a TAN and fetch the associated company name, status and address.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tan" ], "properties": { "tan": { "type": "string", "description": "10-character TAN" } } }, "example": { "tan": "DELA14869B" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "email_id": { "type": "string" }, "verified": { "type": "boolean" }, "tan_number": { "type": "string" }, "company_name": { "type": "string" } } }, "example": { "status": "sample", "email_id": "sample", "verified": true, "tan_number": "sample", "company_name": "Rohit Sharma" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/uan-advanced-v3": { "post": { "operationId": "uanAdvancedV3", "tags": [ "employment" ], "summary": "UAN Advanced V3", "description": "Employment lookup by mobile number, with EPFO passbook for the last 3 months.\n\nA MOBILE MATCHING MANY RECORDS IS CURRENTLY AN ERROR, NOT A RESULT. If the number is linked to more records than the source will return, the call fails with 502 VENDOR_ERROR and the reason “Too many responses” rather than a list. That is a definitive outcome — retrying will not help. Treat it as “narrow the query” and, where you can, use a more specific lookup. We are reviewing this classification with the source and expect to return it as a normal response rather than an error.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "Mobile number linked to the EPFO/UAN record", "pattern": "^[6-9][0-9]{9}$" } }, "additionalProperties": false }, "example": { "mobile": "9876543210" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/uan-advanced-v4": { "post": { "operationId": "uanAdvancedV4", "tags": [ "employment" ], "summary": "UAN Advanced V4", "description": "Employment history since 2012 by mobile number, with EPFO passbook for the last 3 months.\n\nA MOBILE MATCHING MANY RECORDS IS CURRENTLY AN ERROR, NOT A RESULT. If the number is linked to more records than the source will return, the call fails with 502 VENDOR_ERROR and the reason “Too many responses” rather than a list. That is a definitive outcome — retrying will not help. Treat it as “narrow the query” and, where you can, use a more specific lookup. We are reviewing this classification with the source and expect to return it as a normal response rather than an error.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "Mobile number linked to the EPFO/UAN record", "pattern": "^[6-9][0-9]{9}$" } }, "additionalProperties": false }, "example": { "mobile": "9876543210" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/uan-basic-v3": { "post": { "operationId": "uanBasicV3", "tags": [ "employment" ], "summary": "UAN Basic V3", "description": "Latest employment lookup by mobile number (UAN + current employer).\n\nA MOBILE MATCHING MANY RECORDS IS CURRENTLY AN ERROR, NOT A RESULT. If the number is linked to more records than the source will return, the call fails with 502 VENDOR_ERROR and the reason “Too many responses” rather than a list. That is a definitive outcome — retrying will not help. Treat it as “narrow the query” and, where you can, use a more specific lookup. We are reviewing this classification with the source and expect to return it as a normal response rather than an error.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "Mobile number linked to the EPFO/UAN record", "pattern": "^[6-9][0-9]{9}$" } }, "additionalProperties": false }, "example": { "mobile": "9876543210" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/uan-basic-v4": { "post": { "operationId": "uanBasicV4", "tags": [ "employment" ], "summary": "UAN Basic V4", "description": "Employment history since 2012 by mobile number (UAN + employers).\n\nA MOBILE MATCHING MANY RECORDS IS CURRENTLY AN ERROR, NOT A RESULT. If the number is linked to more records than the source will return, the call fails with 502 VENDOR_ERROR and the reason “Too many responses” rather than a list. That is a definitive outcome — retrying will not help. Treat it as “narrow the query” and, where you can, use a more specific lookup. We are reviewing this classification with the source and expect to return it as a normal response rather than an error.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile" ], "properties": { "mobile": { "type": "string", "description": "Mobile number linked to the EPFO/UAN record", "pattern": "^[6-9][0-9]{9}$" } }, "additionalProperties": false }, "example": { "mobile": "9876543210" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": {} } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/vehicle-rc-v1": { "post": { "operationId": "vehicleRcV1", "tags": [ "kyc" ], "summary": "Vehicle RC Verification", "description": "Fetch RC (Registration Certificate) details for a vehicle from VAHAN.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rc_number" ], "properties": { "rc_number": { "type": "string", "pattern": "^[A-Z]{2}[0-9]{1,2}[A-Z]{0,3}[0-9]{1,4}$" } }, "additionalProperties": false }, "example": { "rc_number": "RJ14CV0002" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "fuel_type": { "type": "string" }, "rc_number": { "type": "string" }, "owner_name": { "type": "string" }, "maker_model": { "type": "string" }, "fitness_upto": { "type": "string", "format": "date" }, "vehicle_class": { "type": "string" }, "insurance_upto": { "type": "string", "format": "date" }, "registration_date": { "type": "string", "format": "date" } } }, "example": { "verified": true, "fuel_type": "sample", "rc_number": "RJ14CV0002", "owner_name": "sample", "maker_model": "sample", "fitness_upto": "1990-01-15", "vehicle_class": "RJ14CV0002", "insurance_upto": "1990-01-15", "registration_date": "1990-01-15" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/voter-id-v1": { "post": { "operationId": "voterIdV1", "tags": [ "kyc" ], "summary": "Voter ID Verification", "description": "Verifies an EPIC (voter ID) number against the Election Commission record and returns the registered name, relation, gender, age, state, district and constituency.\n\nNo record found returns 404 and is not charged. Names on the electoral roll are often spelled differently from PAN/Aadhaar — match with tolerance.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "epic_number" ], "properties": { "epic_number": { "type": "string", "pattern": "^[A-Z]{3}[0-9]{7}$", "description": "10-character EPIC number, e.g. ABC1234567." } }, "additionalProperties": false }, "example": { "epic_number": "RJK1234567" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" }, "epic_number": { "type": "string" }, "name": { "type": "string" }, "relation_name": { "type": "string" }, "relation_type": { "type": "string" }, "gender": { "type": "string" }, "age": { "type": "string" }, "state": { "type": "string" }, "district": { "type": "string" }, "assembly_constituency": { "type": "string" }, "parliamentary_constituency": { "type": "string" }, "polling_station": { "type": "string" }, "details": { "type": "object", "description": "Every field the source returned." } } }, "example": { "verified": true, "epic_number": "RJK1234567", "name": "RAHUL VERMA", "relation_name": "SURESH VERMA", "relation_type": "Father", "gender": "M", "age": "34", "state": "Rajasthan", "district": "Jaipur", "assembly_constituency": "Malviya Nagar" } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "404": { "description": "No voter record for that EPIC number. Definitive; not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-cancel-ewb-v1": { "post": { "operationId": "einvoiceCancelEwbV1", "tags": [ "gst" ], "summary": "Cancel E-Way Bill (E-Invoice)", "description": "Cancel an e-way bill that was generated through the e-invoice system.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-cancel-irn-v1": { "post": { "operationId": "einvoiceCancelIrnV1", "tags": [ "gst" ], "summary": "Cancel IRN", "description": "Cancel a registered IRN within the window the portal permits.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-extract-qr-v1": { "post": { "operationId": "einvoiceExtractQrV1", "tags": [ "gst" ], "summary": "Extract Signed QR Code", "description": "Decode the signed QR payload on an e-invoice and return its contents in readable form.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-extract-signed-invoice-v1": { "post": { "operationId": "einvoiceExtractSignedInvoiceV1", "tags": [ "gst" ], "summary": "Extract Signed Invoice", "description": "Decode the signed invoice payload returned at IRN generation.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-generate-ewb-by-irn-v1": { "post": { "operationId": "einvoiceGenerateEwbByIrnV1", "tags": [ "gst" ], "summary": "Generate E-Way Bill from IRN", "description": "Raise an e-way bill directly against an already-registered IRN, without re-keying the invoice.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-generate-irn-bulk-v1": { "post": { "operationId": "einvoiceGenerateIrnBulkV1", "tags": [ "gst" ], "summary": "Generate IRN — Large Invoice", "description": "Register an invoice carrying up to 1000 line items. Same contract as Generate IRN, sized for bulk documents.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-generate-irn-v1": { "post": { "operationId": "einvoiceGenerateIrnV1", "tags": [ "gst" ], "summary": "Generate IRN", "description": "Register an invoice and obtain its IRN, signed QR code and acknowledgement.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-generate-qr-image-v1": { "post": { "operationId": "einvoiceGenerateQrImageV1", "tags": [ "gst" ], "summary": "Generate QR Image", "description": "Render a signed QR payload as an image for printing on the invoice.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-get-by-ack-v1": { "post": { "operationId": "einvoiceGetByAckV1", "tags": [ "gst" ], "summary": "Get E-Invoice by Acknowledgement", "description": "Fetch a registered e-invoice using its acknowledgement number.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "ackNo=112010000123456" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-get-by-irn-v1": { "post": { "operationId": "einvoiceGetByIrnV1", "tags": [ "gst" ], "summary": "Get E-Invoice by IRN", "description": "Fetch a registered e-invoice using its IRN.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "irn=a5c12d...64charirn" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-get-ewb-by-irn-v1": { "post": { "operationId": "einvoiceGetEwbByIrnV1", "tags": [ "gst" ], "summary": "Get E-Way Bill Details by IRN", "description": "Fetch the e-way bill details attached to a registered IRN.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "irn=a5c12d...64charirn" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-get-irn-by-doc-v1": { "post": { "operationId": "einvoiceGetIrnByDocV1", "tags": [ "gst" ], "summary": "Get IRN by Document Details", "description": "Find the IRN for an invoice from its document type, number and date.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "doctype=INV&docnum=INV-2026-0042&docdate=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-get-qr-image-v1": { "post": { "operationId": "einvoiceGetQrImageV1", "tags": [ "gst" ], "summary": "Get QR Image", "description": "Retrieve a previously generated QR image.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "irn=a5c12d...64charirn" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-get-taxpayer-v1": { "post": { "operationId": "einvoiceGetTaxpayerV1", "tags": [ "gst" ], "summary": "E-Invoice Taxpayer Lookup", "description": "Check whether a GSTIN is enabled for e-invoicing and fetch its registered details.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "gstin=29AAACR5055K1Z5" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/einvoice-sync-gstin-v1": { "post": { "operationId": "einvoiceSyncGstinV1", "tags": [ "gst" ], "summary": "Sync GSTIN from Common Portal", "description": "Refresh a GSTIN's details from the GST common portal when the e-invoice system holds stale data.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "gstin=29AAACR5055K1Z5" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-cancel-v1": { "post": { "operationId": "ewbCancelV1", "tags": [ "gst" ], "summary": "Cancel E-Way Bill", "description": "Cancel an e-way bill you generated. Only permitted within the window the portal allows and before verification in transit.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-closure-v1": { "post": { "operationId": "ewbClosureV1", "tags": [ "gst" ], "summary": "Close E-Way Bill", "description": "Close an e-way bill so it can no longer be acted on.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-extend-validity-v1": { "post": { "operationId": "ewbExtendValidityV1", "tags": [ "gst" ], "summary": "Extend E-Way Bill Validity", "description": "Extend validity on a consignment still in transit. Allowed only inside the portal's permitted window around expiry.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-generate-consolidated-v1": { "post": { "operationId": "ewbGenerateConsolidatedV1", "tags": [ "gst" ], "summary": "Generate Consolidated E-Way Bill", "description": "Combine several e-way bills moving on one vehicle into a single consolidated bill (trip sheet).\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-generate-v1": { "post": { "operationId": "ewbGenerateV1", "tags": [ "gst" ], "summary": "Generate E-Way Bill", "description": "Generate an e-way bill for a consignment. Returns the EWB number and validity.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-by-date-v1": { "post": { "operationId": "ewbGetByDateV1", "tags": [ "gst" ], "summary": "Get E-Way Bills by Date", "description": "List the e-way bills you generated on a given date.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "date=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-by-document-v1": { "post": { "operationId": "ewbGetByDocumentV1", "tags": [ "gst" ], "summary": "Get E-Way Bill by Document", "description": "Find the e-way bill generated against a specific consignor document.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "docNo=INV-2026-0042&docDate=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-by-other-party-v1": { "post": { "operationId": "ewbGetByOtherPartyV1", "tags": [ "gst" ], "summary": "Get E-Way Bills Raised by Others", "description": "List e-way bills other parties have raised against your GSTIN.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "date=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-consolidated-v1": { "post": { "operationId": "ewbGetConsolidatedV1", "tags": [ "gst" ], "summary": "Get Consolidated E-Way Bills", "description": "Fetch a consolidated e-way bill (trip sheet) and the bills it covers.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "tripSheetNo=123456789012" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-error-list-v1": { "post": { "operationId": "ewbGetErrorListV1", "tags": [ "gst" ], "summary": "E-Way Bill Error List", "description": "The portal's current error-code list, useful for mapping rejection reasons to messages.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-for-transporter-day-v1": { "post": { "operationId": "ewbGetForTransporterDayV1", "tags": [ "gst" ], "summary": "Get E-Way Bills Assigned to Transporter — by Day", "description": "As a transporter, list the e-way bills assigned to you for a given day.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "date=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-for-transporter-gstin-v1": { "post": { "operationId": "ewbGetForTransporterGstinV1", "tags": [ "gst" ], "summary": "Get E-Way Bills Assigned to Transporter — by GSTIN", "description": "As a transporter, list the e-way bills assigned to you by a particular GSTIN.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "gstin=29AAACR5055K1Z5&date=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-hsn-v1": { "post": { "operationId": "ewbGetHsnV1", "tags": [ "gst" ], "summary": "HSN Code Lookup", "description": "Resolve an HSN code to its official description.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "hsncode=8471" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-rejected-v1": { "post": { "operationId": "ewbGetRejectedV1", "tags": [ "gst" ], "summary": "Get E-Way Bills Rejected by Others", "description": "List your e-way bills that the counterparty has rejected.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "date=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-taxpayer-v1": { "post": { "operationId": "ewbGetTaxpayerV1", "tags": [ "gst" ], "summary": "E-Way Bill Taxpayer Lookup", "description": "Look up a taxpayer's registration details as the e-way bill system holds them.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "GSTIN=29AAACR5055K1Z5" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-transporter-by-state-v1": { "post": { "operationId": "ewbGetTransporterByStateV1", "tags": [ "gst" ], "summary": "Get E-Way Bills for Transporter by State", "description": "As a transporter, list assigned e-way bills filtered by state.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "state=KA&date=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-transporter-v1": { "post": { "operationId": "ewbGetTransporterV1", "tags": [ "gst" ], "summary": "Enrolled Transporter Lookup", "description": "Look up a transporter enrolled on the e-way bill system by their transporter ID.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "transporterId=29AAACR5055K1Z5" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-get-v1": { "post": { "operationId": "ewbGetV1", "tags": [ "gst" ], "summary": "Get E-Way Bill", "description": "Fetch a single e-way bill by its number, with full Part-A and Part-B detail.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "ewbNo=123456789012" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-multivehicle-add-v1": { "post": { "operationId": "ewbMultivehicleAddV1", "tags": [ "gst" ], "summary": "Add Vehicle to Multi-Vehicle Movement", "description": "Add vehicle details to an initiated multi-vehicle movement.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-multivehicle-change-v1": { "post": { "operationId": "ewbMultivehicleChangeV1", "tags": [ "gst" ], "summary": "Change Vehicle on Multi-Vehicle Movement", "description": "Change vehicle details already recorded against a multi-vehicle movement.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-multivehicle-init-v1": { "post": { "operationId": "ewbMultivehicleInitV1", "tags": [ "gst" ], "summary": "Initiate Multi-Vehicle Movement", "description": "Start a multi-vehicle movement for a single e-way bill, where one consignment is split across vehicles.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-regenerate-consolidated-v1": { "post": { "operationId": "ewbRegenerateConsolidatedV1", "tags": [ "gst" ], "summary": "Re-generate Consolidated E-Way Bill", "description": "Re-issue a consolidated e-way bill (trip sheet), typically after a vehicle change.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-reject-v1": { "post": { "operationId": "ewbRejectV1", "tags": [ "gst" ], "summary": "Reject E-Way Bill", "description": "Reject an e-way bill raised against your GSTIN by another party.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-report-by-transporter-date-v1": { "post": { "operationId": "ewbReportByTransporterDateV1", "tags": [ "gst" ], "summary": "E-Way Bill Report by Assigned Date", "description": "Transporter-assigned e-way bill report for a given assignment date.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nPARAMETERS ARE RELAYED VERBATIM. Put the portal’s documented query parameters in `query_string` exactly as the portal names them — they are case-sensitive and we do not rewrite them.\n\nTHE SAMPLE BELOW IS ILLUSTRATIVE unless noted. Two parameter names are confirmed against the live portal: `GSTIN=` on the taxpayer lookup (upper case) and `hsncode=` on the HSN lookup (lower case) — the portal is inconsistent about casing, which is why we relay rather than normalise. For every other read, check the portal specification; if a parameter is rejected, the portal names the one it wanted and we will correct the sample.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "query_string": { "type": "string", "default": "", "description": "Portal query parameters, e.g. GSTIN=29AAACR5055K1Z5. Relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "query_string": "date=25/08/2026" } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-update-partb-v1": { "post": { "operationId": "ewbUpdatePartbV1", "tags": [ "gst" ], "summary": "Update Part-B / Vehicle Number", "description": "Attach or change the vehicle and transport details (Part-B) on an existing e-way bill.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } }, "/ewb-update-transporter-v1": { "post": { "operationId": "ewbUpdateTransporterV1", "tags": [ "gst" ], "summary": "Update Transporter", "description": "Reassign an e-way bill to a different transporter GSTIN.\n\nCREDENTIALS ARE THE TAXPAYER’S, AND ARE PER CALL. `gstin`, `username` and `password` are the credentials the GST portal issued to that taxpayer for API access — not an API Sathi login. They are sent per request rather than stored against your account, because one customer legitimately files for several GSTINs. They are write-only: they never appear in your call history or in our logs.\n\nDO NOT SEND A REQUEST ID. The portal requires a unique id on every request. We mint it from the call id, so it is guaranteed unique and it ties your call to our trace and the portal’s record — one identifier for a support conversation. A `request_id` you send is ignored.\n\nFAILURE IS NOT CHARGED. The portal reports a rejection in its own body rather than as an HTTP error — a wrong credential, an expired e-way bill, a duplicate document. We surface it as an error with the portal’s reason, release the wallet hold, and you are not billed. You pay for calls the portal accepted.\n\nREADING A 502. A `VENDOR_ERROR` carries the portal’s own words in `reason`, and the wording tells you where the problem is. “Invalid login credentials” or “Incorrect user id” means the taxpayer’s `username`/`password` — not your API Sathi key, and not our platform. Those are issued by the GST portal to that GSTIN and must be enabled for API access there. Anything mentioning a header, an action or a mandatory parameter is ours: send it to us with the call id and we will fix the mapping.\n\nTHE BODY IS RELAYED VERBATIM. Send the portal’s documented request body as `payload` and we pass it through untouched. Consult the e-way bill / e-invoice API specification for the fields this operation expects; the sample below shows the envelope, not the body.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Same key returns the same response for 24h." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "gstin", "username", "password", "payload" ], "properties": { "gstin": { "type": "string", "description": "GSTIN this request is filed for." }, "username": { "type": "string", "description": "The taxpayer’s GST portal API username. Write-only." }, "password": { "type": "string", "description": "The taxpayer’s GST portal API password. Write-only." }, "payload": { "type": "object", "description": "The portal-format request body, relayed unchanged." } } }, "example": { "gstin": "29AAACR5055K1Z5", "username": "your_portal_username", "password": "your_portal_password", "payload": { "note": "The portal-format request body for this operation." } } } } }, "responses": { "200": { "description": "Successful, normalized response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True only when the portal accepted the request." }, "message": { "type": "string", "description": "The portal’s reason when it rejected one." }, "data": { "type": "object", "description": "The portal response, passed through in full." } } }, "example": { "success": true, "data": { "note": "The portal response, relayed unchanged." } } } } }, "401": { "description": "Missing, malformed, or revoked X-API-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "402": { "description": "Wallet balance is below the per-call sale price. Recharge and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "403": { "description": "API key is not scoped for this product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "410": { "description": "This API has been retired and is no longer available. Stop calling it — it will not return. Check the catalog for the current equivalent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "422": { "description": "The request was rejected as invalid — either it failed OUR schema validation (malformed input; not charged), or the upstream source rejected the value you sent. NOTE: an identifier that is well-formed but simply has NO RECORD is no longer an error — it returns 200 with `verified: false` and is charged (see the result-code table below). FIX the input before retrying; retrying the same value will fail again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "429": { "description": "Per-key RPS or RPM limit exceeded. Back off and retry after the Retry-After header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "502": { "description": "Upstream vendor rejected our credentials (our config issue). Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "503": { "description": "No healthy vendor is currently available for this product. Transient — safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } }, "504": { "description": "Upstream vendor did not respond within the SLA window. Safe to retry after a short backoff. Not charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "call_id": { "type": "string" } } } } } } } } } } } } }