{"openapi":"3.1.0","info":{"title":"Grappi API","version":"1.0.0","description":"One contract for India's financial infrastructure. Send your API key as a Bearer token. All money is in integer paise. Security guide: https://grappi.ai/docs/security"},"servers":[{"url":"https://grappi.ai"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Document AI"},{"name":"KYC / Identity"},{"name":"Wealth / MF"},{"name":"Tax"},{"name":"Market Data"},{"name":"CAS (portfolio fetch)"},{"name":"Depository / Broker"},{"name":"Portfolio+"},{"name":"Lending"},{"name":"PMS / AIF"},{"name":"Vehicle / DL"},{"name":"Business / KYB"},{"name":"Employment"},{"name":"Credit"},{"name":"Income (ITR)"},{"name":"Risk & Location"},{"name":"Account"}],"paths":{"/v1/read/document":{"post":{"operationId":"read-document","summary":"Read document → JSON","description":"Any financial file/email → structured JSON via the structured→template→OCR→LLM ladder, with per-field confidence + provenance.\n\nIf the file cannot be read, the call fails and is refunded.","tags":["Document AI"],"x-required-scope":"read:document","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"Name of the file, 1 to 255 characters; the extension helps identify the type."},"content_type":{"type":"string","description":"MIME type of the file, for example text/csv or application/pdf. Defaults to application/octet-stream."},"content_base64":{"type":"string","description":"The file contents, base64-encoded. Must not be empty and must decode to at most 15 MiB."},"declared_type":{"type":"string","description":"What you expect the document to be, if you know. It guides the reader."}},"required":["filename","content_base64"]},"example":{"filename":"statement.csv","content_type":"text/csv","content_base64":"RGF0ZSxOYXJyYXRpb24sV2l0aGRyYXdhbCxEZXBvc2l0LENsb3NpbmcgQmFsYW5jZQowMS8wNC8yMDI0LE9wZW5pbmcsLCwxMDAwMC4wMAowMi8wNC8yMDI0LFVQSSBQYXltZW50LDE1MDAuMDAsLDg1MDAuMDAKMDMvMDQvMjAyNCxTYWxhcnkgQ3JlZGl0LCw1MDAwMC4wMCw1ODUwMC4wMAo="}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"document_type":"bank_statement","issuer":null,"review_required":false,"overall_confidence":0.95,"fields":{"source_filename":{"value":"statement.csv","confidence":1}},"transactions":[],"warnings":[],"tiers_used":["structured"]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/bank-account":{"post":{"operationId":"kyc-penny","summary":"Penny-drop bank account","description":"Verify a bank account + beneficiary name.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_number":{"type":"string","description":"Bank account number, 6 to 20 digits."},"ifsc":{"type":"string","description":"IFSC of the branch: four letters, a zero, then six letters or digits, for example HDFC0001234."}},"required":["account_number","ifsc"]},"example":{"account_number":"123456782","ifsc":"HDFC0001234"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"account_number_masked":"*****6782","ifsc":"HDFC0001234","valid":true,"name_at_bank":"ASHA RAO"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/lookup/ifsc":{"get":{"operationId":"ifsc","summary":"IFSC lookup","description":"Bank + branch for an IFSC.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[{"name":"ifsc","in":"query","required":true,"description":"IFSC to look up: four letters, a zero, then six letters or digits, for example ICIC0000001.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"ifsc":"ICIC0000001","valid":true,"bank":"EXAMPLE BANK","branch":"EXAMPLE BRANCH"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/mf/scheme-master":{"get":{"operationId":"mf-scheme","summary":"MF scheme master","description":"Scheme metadata (AMC, category, ISIN).\n\nThis reply has no balance_minor. An unknown scheme_code returns NOT_FOUND.","tags":["Wealth / MF"],"x-required-scope":"mf:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"scheme_code","in":"query","required":true,"description":"The mutual-fund scheme code published by AMFI, for example 120503.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"scheme_code":"120503","scheme_name":"Sample Flexi Cap Fund - Direct - Growth","amc":"Sample Mutual Fund","category":"equity","isin":"INF123K01014"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/mf/nav":{"get":{"operationId":"mf-nav","summary":"MF NAV history","description":"Latest + historical NAV (AMFI).\n\nThis reply has no balance_minor. A scheme with no NAV on record returns NOT_FOUND.","tags":["Wealth / MF"],"x-required-scope":"mf:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"scheme_code","in":"query","required":true,"description":"The mutual-fund scheme code published by AMFI, for example 120503.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"latest":{"date":"2024-03-01","nav_minor":5120000},"history":[{"date":"2024-01-01","nav_minor":5000000},{"date":"2024-02-01","nav_minor":5060000},{"date":"2024-03-01","nav_minor":5120000}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/mf/capital-gains":{"post":{"operationId":"mf-capgains","summary":"Capital gains + XIRR","description":"FIFO matching, STCG/LTCG, grandfathering, XIRR.\n\nTransactions may be sent in any order; they are sorted by date before matching.","tags":["Wealth / MF"],"x-required-scope":"mf:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transactions":{"type":"array","description":"Non-empty list of buys and sells of one scheme.","items":{"type":"object","properties":{"date":{"type":"string","description":"Transaction date as YYYY-MM-DD or a full ISO 8601 date-time."},"type":{"type":"string","description":"buy or sell."},"units":{"type":"number","description":"Units bought or sold; must be above 0."},"price_minor":{"type":"integer","description":"NAV per unit in paise; 0 or more."}},"required":["date","type","units","price_minor"]}},"ltcg_days":{"type":"integer","description":"Holding days after which a gain counts as long-term; above 0. Defaults to 365."},"fmv_31jan2018_minor":{"type":"integer","description":"Fair market value per unit on 31 January 2018 in paise, to apply grandfathering to older units."},"current_nav_minor":{"type":"integer","description":"Today's NAV per unit in paise, to include units still held in the XIRR. Needs valuation_date too."},"valuation_date":{"type":"string","description":"Date of current_nav_minor, as YYYY-MM-DD."}},"required":["transactions"]},"example":{"transactions":[{"date":"2022-01-01","type":"buy","units":100,"price_minor":10000},{"date":"2024-01-01","type":"sell","units":100,"price_minor":15000}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"realized":[{"buy_date":"2022-01-01","sell_date":"2024-01-01","units":100,"term":"LTCG","proceeds_minor":1500000,"cost_minor":1000000,"gain_minor":500000}],"total_stcg_minor":0,"total_ltcg_minor":500000,"total_gain_minor":500000,"xirr":0.224745,"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/tax/income":{"post":{"operationId":"tax-income","summary":"Income tax calculator","description":"Old/new regime, slabs, §87A, surcharge, cess.\n\nSurcharge marginal relief is not applied, so results just above a surcharge threshold come out slightly high.","tags":["Tax"],"x-required-scope":"tax:calc","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"regime":{"type":"string","description":"old or new."},"gross_income_minor":{"type":"integer","description":"Gross yearly income in paise; 0 or more."},"salaried":{"type":"boolean","description":"True to apply the standard deduction for salaried people. Defaults to false."},"deductions_minor":{"type":"integer","description":"Chapter VI-A deductions such as 80C in paise. Used only under the old regime; ignored under the new one."}},"required":["regime","gross_income_minor"]},"example":{"regime":"new","gross_income_minor":120000000,"salaried":true}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"regime":"new","taxable_income_minor":112500000,"base_tax_minor":6875000,"rebate_87a_minor":0,"surcharge_minor":0,"cess_minor":275000,"total_tax_minor":7150000}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/tax/capital-gains":{"post":{"operationId":"tax-capgains","summary":"Capital-gains tax","description":"Equity STCG/LTCG tax with the one-lakh LTCG exemption and cess.\n\nRates and the exemption are applied exactly as you send them. If you leave them out, the defaults shown above are used, so pass the current figures explicitly.","tags":["Tax"],"x-required-scope":"tax:calc","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"equity_stcg_minor":{"type":"integer","description":"Short-term equity gain in paise; 0 or more. Defaults to 0."},"equity_ltcg_minor":{"type":"integer","description":"Long-term equity gain in paise; 0 or more. Defaults to 0."},"stcg_rate":{"type":"number","description":"Short-term tax rate as a fraction from 0 to 1. Defaults to 0.15; send the rate you want applied."},"ltcg_rate":{"type":"number","description":"Long-term tax rate as a fraction from 0 to 1. Defaults to 0.10; send the rate you want applied."},"ltcg_exemption_minor":{"type":"integer","description":"Yearly long-term exemption in paise. Defaults to 10000000 (Rs 1,00,000); send the amount you want applied."}}},"example":{"equity_ltcg_minor":15000000}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"stcg_tax_minor":0,"ltcg_taxable_minor":5000000,"ltcg_exemption_applied_minor":10000000,"ltcg_tax_minor":500000,"cess_minor":20000,"total_tax_minor":520000}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/marketdata/sources":{"get":{"operationId":"marketdata-sources","summary":"Data-source licence matrix","description":"The attribution each market-data feed's licence obliges you to display, and whether you may redistribute it to your own users.\n\nCheck this before you show market data to your own customers: where redistributable is false you must not display it, and where attribution is present you must show it.","tags":["Market Data"],"x-required-scope":"marketdata:read","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"fx":{"redistributable":true},"equity":{"redistributable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/request/providers":{"get":{"operationId":"cas-providers","summary":"CAS provider matrix","description":"Which RTAs can be requested server-side today (KFintech yes; NSDL/CDSL need an investor OTP, so use the mailbox scan instead).\n\nCheck request_automatable before placing a request. For sources where it is false, use the mailbox scan or an upload instead.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:request","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"sources":[{"source":"kfintech","covers":"mutual_funds","request_automatable":true},{"source":"cams","covers":"mutual_funds","request_automatable":true},{"source":"nsdl","covers":"demat","request_automatable":false,"reason":"Needs a one-time code sent to the investor, so read the statement from their mailbox instead."},{"source":"cdsl","covers":"demat","request_automatable":false,"reason":"Needs a one-time code sent to the investor, so read the statement from their mailbox instead."}],"captcha_solver":{"available":true,"one_call_request":"POST /v1/cas/request/auto"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/request/session":{"post":{"operationId":"cas-request-session","summary":"3.1 CAS Auto Request — open session","description":"Opens a session with the RTA and returns the CAPTCHA image the investor must read.\n\nStep 1 of 2. Show the picture to the investor, then call submit with session_id and what they typed, within 10 minutes.\n\nEach session can be used once. If the answer is wrong or the session expires, open a new one.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:request","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Which issuer to request from: kfintech, cams, nsdl or cdsl. Only sources with request_automatable true work."}},"required":["source"]},"example":{"source":"kfintech"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"session_id":"cassn_1a2b3c4d5e6f7a8b","source":"kfintech","captcha_image":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUg==","expires_at":"2026-11-06T09:40:00.000Z","instructions":"Show captcha_image to the investor, then POST the characters to /v1/cas/request/submit."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/request/submit":{"post":{"operationId":"cas-request-submit","summary":"3.1 CAS Auto Request — submit","description":"Submits the statement request with the CAPTCHA answer. The RTA then e-mails the password-protected CAS to the investor.\n\nStep 2 of 2, after opening a session. Unknown fields in the body are rejected.\n\nThe issuer e-mails the PDF to the investor, locked with cas_password. Then read it with the mailbox scan or an upload.\n\nIf period is specific, from_date and to_date are both required.\n\nA reply with accepted false (for example a wrong CAPTCHA) is still a completed call and is charged. Open a new session and try again.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:request","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","description":"The session_id from opening a session; 3 to 64 characters."},"pan":{"type":"string","description":"Investor PAN in capitals, for example ABCPE1234F; the fourth letter must be one of A, B, C, F, G, H, L, J, P, T."},"email":{"type":"string","description":"Where the issuer e-mails the statement; up to 120 characters."},"statement_type":{"type":"string","description":"summary or detailed. Defaults to summary (detailed adds every transaction)."},"period":{"type":"string","description":"current_fy, previous_fy or specific. Defaults to current_fy."},"from_date":{"type":"string","description":"Start date as DD/MM/YYYY. Required when period is specific."},"to_date":{"type":"string","description":"End date as DD/MM/YYYY. Required when period is specific."},"cas_password":{"type":"string","description":"Password the PDF will be locked with: 8 to 12 characters with a capital letter, a small letter, a digit and a symbol."},"include_zero_balance_folios":{"type":"boolean","description":"Also list folios with no units left. Defaults to false."},"captcha":{"type":"string","description":"The characters the investor read from the picture; 1 to 10 characters."}},"required":["session_id","pan","email","cas_password","captcha"]},"example":{"session_id":"cassn_replace_me","pan":"ABCPA1234A","email":"investor@example.com","statement_type":"detailed","period":"current_fy","cas_password":"Grappi@2026","captcha":"AB12CD"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"request_id":"casrq_1a2b3c4d5e6f7a8b","source":"kfintech","status":"submitted","pan":"******234F","email":"asha.rao@example.com","statement_type":"detailed","period":"current_fy","from_date":null,"to_date":null,"rta_code":null,"message":"Your request has been received. The statement will be e-mailed shortly.","created_at":"2026-11-06T09:30:00.000Z","submitted_at":"2026-11-06T09:30:04.000Z","accepted":true,"next":"The RTA mails the PDF to the investor. Pick it up with POST /v1/cas/read/mailbox/scan, or upload it to POST /v1/cas/read."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/request/auto":{"post":{"operationId":"cas-request-auto","summary":"3.1 CAS Auto Request — one call","description":"Opens the RTA session, completes its verification step and submits, retrying with a fresh session on a misread. One call, one price regardless of attempts.\n\nDoes the CAPTCHA step for you. The price is the same however many attempts it takes.\n\nCheck the cas-providers call first: if the one-call request is not available, this returns a validation error and you must use the two-step flow.\n\nUnknown fields in the body are rejected. If period is specific, from_date and to_date are both required.\n\nA reply with accepted false is still a completed call and is charged.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:request","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Which issuer to request from: kfintech, cams, nsdl or cdsl. Only sources with request_automatable true work."},"pan":{"type":"string","description":"Investor PAN in capitals, for example ABCPE1234F; the fourth letter must be one of A, B, C, F, G, H, L, J, P, T."},"email":{"type":"string","description":"Where the issuer e-mails the statement; up to 120 characters."},"statement_type":{"type":"string","description":"summary or detailed. Defaults to summary (detailed adds every transaction)."},"period":{"type":"string","description":"current_fy, previous_fy or specific. Defaults to current_fy."},"from_date":{"type":"string","description":"Start date as DD/MM/YYYY. Required when period is specific."},"to_date":{"type":"string","description":"End date as DD/MM/YYYY. Required when period is specific."},"cas_password":{"type":"string","description":"Password the PDF will be locked with: 8 to 12 characters with a capital letter, a small letter, a digit and a symbol."},"include_zero_balance_folios":{"type":"boolean","description":"Also list folios with no units left. Defaults to false."},"max_attempts":{"type":"integer","description":"How many times to retry with a fresh CAPTCHA, from 1 to 5. Defaults to 3."}},"required":["source","pan","email","cas_password"]},"example":{"source":"kfintech","pan":"ABCPA1234A","email":"investor@example.com","statement_type":"detailed","period":"current_fy","cas_password":"Grappi@2026","max_attempts":3}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"request_id":"casrq_1a2b3c4d5e6f7a8b","source":"kfintech","status":"submitted","pan":"******234F","email":"asha.rao@example.com","statement_type":"detailed","period":"current_fy","from_date":null,"to_date":null,"rta_code":null,"message":"Your request has been received. The statement will be e-mailed shortly.","created_at":"2026-11-06T09:30:00.000Z","submitted_at":"2026-11-06T09:30:04.000Z","accepted":true,"attempts":[{"attempt":1,"outcome":"accepted"}],"next":"The RTA mails the PDF to the investor. Pick it up with POST /v1/cas/read/mailbox/scan, or upload it to POST /v1/cas/read."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/read/mailbox/scan":{"post":{"operationId":"cas-read-mailbox","summary":"3.2 CAS Auto Read — mailbox scan","description":"Finds the RTA's mail over IMAP, pulls the attachment, decrypts and parses it. Use an app password.\n\nSend either cas_password (CAMS, KFintech statements) or pan (NSDL, CDSL statements) so the PDF can be opened. Unknown fields in the body are rejected.\n\nMailbox login details are used for this call only and are not stored.\n\nEach call is charged to your wallet, and works only once this API is activated for your account.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string","description":"Mail server host, 3 to 200 characters, for example imap.gmail.com."},"port":{"type":"integer","description":"Mail server port, 1 to 65535. Defaults to 993."},"secure":{"type":"boolean","description":"Use an encrypted connection. Defaults to true."},"user":{"type":"string","description":"Mailbox login, 3 to 200 characters."},"password":{"type":"string","description":"Mailbox password, 1 to 300 characters. Use an app password, not the main account password."},"mailbox":{"type":"string","description":"Folder to search, 1 to 100 characters. Uses the account's main inbox when left out."},"since_days":{"type":"integer","description":"How far back to look, from 1 to 730 days. Defaults to 120."},"max_messages":{"type":"integer","description":"Most messages to check, from 1 to 100. Defaults to 25."},"extra_senders":{"type":"array","description":"Up to 10 extra sender addresses or domains to accept, each 3 to 200 characters.","items":{}},"cas_password":{"type":"string","description":"The password chosen when the statement was requested (CAMS, KFintech); up to 64 characters. Send this or pan."},"pan":{"type":"string","description":"The investor's PAN, which opens NSDL and CDSL statements. Send this or cas_password."},"dob":{"type":"string","description":"Date of birth as YYYY-MM-DD, for statements that need it."},"limit":{"type":"integer","description":"How many of the newest statements to read, from 1 to 10. Defaults to 1."}},"required":["host","user","password"]},"example":{"host":"imap.gmail.com","port":993,"secure":true,"user":"investor@gmail.com","password":"app-specific-password","cas_password":"Grappi@2026","since_days":120}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"found":1,"parsed":1,"documents":[{"email":{"from":"statements@example.com","subject":"Your Consolidated Account Statement","received_at":"2026-11-02T06:10:00.000Z","filename":"cas_statement.pdf"},"source":"cams","statement_type":"detailed","investor_name":"ASHA RAO","investor_email":"asha.rao@example.com","pan":"******234F","period_from":"2023-04-01","period_to":"2024-03-31","holding_count":1,"transaction_count":1,"total_value_minor":4412035,"folios":[{"folio":"1234567/89","amc":"Sample Mutual Fund","scheme":"Sample Liquid Fund - Growth","isin":"INF123K01014","units":124.239,"nav_minor":35512,"value_minor":4412035,"cost_minor":4000250,"as_of":"2024-03-31"}],"demat":[],"transactions":[{"folio":"1234567/89","scheme":"Sample Liquid Fund - Growth","isin":"INF123K01014","date":"2023-06-12","description":"Purchase","type":"purchase","amount_minor":4000250,"units":124.239,"nav_minor":32198,"balance_units":124.239}],"confidence":0.97,"review_required":false,"warnings":[]}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/import/document":{"post":{"operationId":"cas-import-document","summary":"3.3 CAS Auto Import — import parsed CAS","description":"Folds a parsed CAS into the portfolio: one stable key per position (so next month updates rather than duplicates), cost/value/gain rolled up, XIRR when available.\n\nUse this when you already have the statement as JSON, for example from the read call. A body with no folios and no demat lines is refused.\n\nImporting the next month's statement updates existing positions by key instead of adding duplicates.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:import","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Who issued the statement: kfintech, cams, nsdl or cdsl."},"statement_type":{"type":"string","description":"summary or detailed."},"period_from":{"type":"string","description":"Statement period start, up to 20 characters."},"period_to":{"type":"string","description":"Statement period end, up to 20 characters."},"folios":{"type":"array","description":"Mutual-fund folio lines, up to 2000. Send at least one folio or one demat line.","items":{"type":"object","properties":{"folio":{"type":"string","description":"Folio number, up to 60 characters."},"amc":{"type":"string","description":"Fund house, up to 160 characters."},"scheme":{"type":"string","description":"Scheme name, up to 240 characters."},"isin":{"type":"string","description":"Scheme ISIN, up to 20 characters."},"units":{"type":"number","description":"Units held. Defaults to 0."},"nav_minor":{"type":"integer","description":"NAV per unit in paise."},"value_minor":{"type":"integer","description":"Market value in paise."},"cost_minor":{"type":"integer","description":"Cost in paise."},"as_of":{"type":"string","description":"Valuation date, up to 20 characters."}}}},"demat":{"type":"array","description":"Demat holding lines, up to 2000.","items":{"type":"object","properties":{"dp_id":{"type":"string","description":"Depository participant id, up to 30 characters."},"client_id":{"type":"string","description":"Demat client id, up to 30 characters."},"isin":{"type":"string","description":"Security ISIN, up to 20 characters."},"security":{"type":"string","description":"Security name, up to 240 characters."},"quantity":{"type":"number","description":"Quantity held. Defaults to 0."},"price_minor":{"type":"integer","description":"Price per unit in paise."},"value_minor":{"type":"integer","description":"Market value in paise."},"asset_class":{"type":"string","description":"Asset class, up to 40 characters."},"as_of":{"type":"string","description":"Valuation date, up to 20 characters."}}}},"transactions":{"type":"array","description":"Transactions, up to 20000. Needed for an XIRR.","items":{"type":"object","properties":{"folio":{"type":"string","description":"Folio number, up to 60 characters."},"scheme":{"type":"string","description":"Scheme name, up to 240 characters."},"isin":{"type":"string","description":"ISIN, up to 20 characters."},"date":{"type":"string","description":"Transaction date, up to 20 characters; required for each transaction you send."},"description":{"type":"string","description":"Description, up to 300 characters."},"type":{"type":"string","description":"For example purchase, redemption, switch_in, switch_out or dividend. Defaults to other."},"amount_minor":{"type":"integer","description":"Amount in paise."},"units":{"type":"number","description":"Units bought or sold."},"nav_minor":{"type":"integer","description":"NAV per unit in paise."},"balance_units":{"type":"number","description":"Unit balance after the transaction."}},"required":["date"]}},"review_required":{"type":"boolean","description":"Mark the data as needing a human check. Defaults to false."},"warnings":{"type":"array","description":"Up to 200 notes, each up to 500 characters, kept with the import.","items":{}}}},"example":{"source":"cams","statement_type":"detailed","period_to":"2024-03-31","folios":[{"folio":"1234567/89","scheme":"Test Liquid Fund - Growth","isin":"INF209K01XX1","units":124.239,"nav_minor":35512,"value_minor":4412035,"cost_minor":4000250}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"import_id":"casim_1a2b3c4d5e6f7a8b","source":"cams","imported_at":"2026-11-06T09:30:00.000Z","holding_count":1,"created":1,"updated":0,"unchanged":0,"total_value_minor":4412035,"total_cost_minor":4000250,"total_gain_minor":411785,"xirr_percent":null,"holdings":[{"key":"mutual_fund:INF123K01014:1234567/89","kind":"mutual_fund","name":"Sample Liquid Fund - Growth","isin":"INF123K01014","folio":"1234567/89","units":124.239,"value_minor":4412035,"cost_minor":4000250,"gain_minor":411785,"as_of":"2024-03-31"}],"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/portfolio":{"get":{"operationId":"cas-portfolio","summary":"3.3 CAS Auto Import — current portfolio","description":"The latest imported CAS portfolio for this tenant.\n\nReturns the most recent import. If nothing has been imported yet, the result is only holding_count 0, an empty holdings list and a hint.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:import","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"import_id":"casim_1a2b3c4d5e6f7a8b","source":"cams","imported_at":"2026-11-06T09:30:00.000Z","holding_count":1,"created":1,"updated":0,"unchanged":0,"total_value_minor":4412035,"total_cost_minor":4000250,"total_gain_minor":411785,"xirr_percent":null,"holdings":[{"key":"mutual_fund:INF123K01014:1234567/89","kind":"mutual_fund","name":"Sample Liquid Fund - Growth","isin":"INF123K01014","folio":"1234567/89","units":124.239,"value_minor":4412035,"cost_minor":4000250,"gain_minor":411785,"as_of":"2024-03-31"}],"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/connect":{"post":{"operationId":"broker-connect","summary":"Unified broker connect / Connect LIVE account (real data)","description":"Link a broker account — 13 brokers behind one contract, the broker is just a parameter. Sandbox needs no credentials.\n\nConnect first, then pass connection_id to every other broker call. Sandbox needs no credentials and returns simulated data.\n\nLive mode uses your own broker API credentials. They are stored encrypted and never returned.\n\nBrokers issue a new access token each day; replace it with the token rotate call.\n\nBrokers that offer a hosted login can be linked with login start and login callback instead of sending credentials.\n\nPass your own broker API credentials to get REAL holdings/orders. Groww: token from groww.in → Settings → Trading APIs. Dhan: web.dhan.co. Credentials are vault-encrypted.\n\nSending credentials links the real account, so holdings, orders and funds are real. Live mode without credentials is refused.\n\nCredentials are stored encrypted and never returned. Brokers issue a new access token each day; replace it with the token rotate call.","tags":["Depository / Broker"],"x-required-scope":"broker:write","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"broker":{"type":"string","description":"Broker name, 2 to 30 characters. One of: zerodha, angel, dhan, upstox, groww, motilal, fyers, shoonya, flattrade, xts, zebu, tradesmart, arrow. Common short names such as kite or angelone are also accepted."},"mode":{"type":"string","description":"sandbox for simulated data or live for the real account. Defaults to live when credentials are sent, otherwise sandbox."},"label":{"type":"string","description":"Your own name for this connection, up to 80 characters."},"credentials":{"type":"object","properties":{"api_key":{"type":"string","description":"Your broker API key, 1 to 200 characters."},"api_secret":{"type":"string","description":"Your broker API secret, 1 to 200 characters."},"access_token":{"type":"string","description":"The broker's access token for today, 1 to 2000 characters."},"client_id":{"type":"string","description":"Your broker client id, 1 to 100 characters."},"base_url":{"type":"string","description":"Broker host URL, up to 300 characters; only for brokers on the xts platform."}},"description":"Your own broker API credentials. Required for live mode; leave out for sandbox. Unknown keys are rejected."}},"required":["broker"]},{"type":"object","properties":{"broker":{"type":"string","description":"Broker name, 2 to 30 characters. One of: zerodha, angel, dhan, upstox, groww, motilal, fyers, shoonya, flattrade, xts, zebu, tradesmart, arrow. Common short names such as kite or angelone are also accepted."},"mode":{"type":"string","description":"sandbox for simulated data or live for the real account. Defaults to live when credentials are sent, otherwise sandbox."},"label":{"type":"string","description":"Your own name for this connection, up to 80 characters."},"credentials":{"type":"object","properties":{"api_key":{"type":"string","description":"Your broker API key, 1 to 200 characters."},"api_secret":{"type":"string","description":"Your broker API secret, 1 to 200 characters."},"access_token":{"type":"string","description":"The broker's access token for today, 1 to 2000 characters."},"client_id":{"type":"string","description":"Your broker client id, 1 to 100 characters."},"base_url":{"type":"string","description":"Broker host URL, up to 300 characters; only for brokers on the xts platform."}},"description":"Your own broker API credentials. Required for live mode; leave out for sandbox. Unknown keys are rejected."}},"required":["broker"]}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"connection_id":"bconn_a1b2c3d4e5f60718","broker":"zerodha","mode":"sandbox","label":"zerodha (sandbox)","status":"connected"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/holdings":{"get":{"operationId":"broker-holdings","summary":"Holdings","description":"Normalized DEMAT holdings + P&L, same shape for every broker.\n\nThe result is a list. The shape is the same for every broker. Send connection_id, or broker for a quick sandbox test.","tags":["Depository / Broker"],"x-required-scope":"broker:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"connection_id","in":"query","required":false,"description":"The connection to use, as returned by connect (3 to 64 characters). Send this or broker.","schema":{"type":"string"}},{"name":"broker","in":"query","required":false,"description":"Quick sandbox test with no connection, by broker name (2 to 30 characters). One of: zerodha, angel, dhan, upstox, groww, motilal, fyers, shoonya, flattrade, xts, zebu, tradesmart, arrow. Send this or connection_id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":[{"isin":"INE123A01012","symbol":"RELIANCE","exchange":"NSE","quantity":10,"avg_cost_minor":250000,"ltp_minor":295000,"market_value_minor":2950000,"pnl_minor":450000}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/connections":{"get":{"operationId":"broker-connections","summary":"List connections","description":"Every linked broker account. Credentials are never returned.\n\nCredentials are never returned.","tags":["Depository / Broker"],"x-required-scope":"broker:read","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"supported_brokers":["zerodha","angel","dhan","upstox","groww","motilal","fyers","shoonya","flattrade","xts","zebu","tradesmart","arrow"],"connections":[{"connection_id":"bconn_a1b2c3d4e5f60718","broker":"zerodha","mode":"live","label":"zerodha (live)","status":"active","created_at":"2026-11-01T05:00:00.000Z"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/connections/{id}/token":{"post":{"operationId":"broker-token-rotate","summary":"Rotate daily token","description":"One uniform call for every broker's daily access-token expiry.\n\nBrokers expire their access token every day. Call this each morning with the new access_token so the connection keeps working.\n\nSandbox connections have no token and are refused; a revoked or unknown connection returns NOT_FOUND.","tags":["Depository / Broker"],"x-required-scope":"broker:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The connection_id of a live connection.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentials":{"type":"object","properties":{"api_key":{"type":"string","description":"Your broker API key, 1 to 200 characters."},"api_secret":{"type":"string","description":"Your broker API secret, 1 to 200 characters."},"access_token":{"type":"string","description":"The broker's access token for today, 1 to 2000 characters."},"client_id":{"type":"string","description":"Your broker client id, 1 to 100 characters."},"base_url":{"type":"string","description":"Broker host URL, up to 300 characters; only for brokers on the xts platform."}},"description":"The new broker credentials; any you send replace the stored ones and the rest are kept. Unknown keys are rejected."}},"required":["credentials"]},"example":{"credentials":{"access_token":"fresh_daily_token"}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"connection_id":"bconn_a1b2c3d4e5f60718","rotated":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/connections/{id}":{"delete":{"operationId":"broker-connection-revoke","summary":"Revoke connection","description":"Revoke a linked account and hard-delete its vaulted credentials.\n\nPermanent: the stored credentials are deleted. Link the account again to use it later.","tags":["Depository / Broker"],"x-required-scope":"broker:write","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The connection_id to remove.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"connection_id":"bconn_a1b2c3d4e5f60718","status":"revoked"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/portfolio":{"get":{"operationId":"portfolio-snapshot","summary":"Consolidated portfolio","description":"Every linked broker plus the imported CAS in one view: holdings deduplicated by ISIN, totals, P&L, allocation, concentration and score. One call, whatever the brokers.\n\nReads every active broker connection, plus your imported statement unless include_cas is false. A broker that fails (for example an expired token) is listed in sources with status failed and its holdings are left out of the totals.\n\nThe same stock held at several brokers appears once in holdings, with the split in contributions.","tags":["Portfolio+"],"x-required-scope":"portfolio:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"connection_ids","in":"query","required":false,"description":"Comma-separated connection ids to include, such as bconn_a,bconn_b. Defaults to every active connection.","schema":{"type":"string"}},{"name":"include_cas","in":"query","required":false,"description":"Send false to leave the imported statement out and use broker accounts only. Defaults to true.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"as_of":"2026-11-07T09:30:00.000Z","totals":{"invested_minor":7750250,"value_minor":8837035,"pnl_minor":1086785,"pnl_percent":14.02,"holding_count":2,"source_count":3,"sources_ok":3,"sources_failed":0},"sources":[{"kind":"broker","id":"bconn_a1b2c3d4e5f60718","provider":"zerodha","label":"zerodha (live)","status":"ok","holding_count":1,"value_minor":2950000},{"kind":"broker","id":"bconn_b2c3d4e5f6071829","provider":"upstox","label":"upstox (live)","status":"ok","holding_count":1,"value_minor":1475000},{"kind":"cas","id":"cas_import","provider":"cas","label":"Imported statement","status":"ok","holding_count":1,"value_minor":4412035}],"holdings":[{"key":"INE123A01012","asset_class":"equity","isin":"INE123A01012","symbol":"RELIANCE","name":"RELIANCE","quantity":15,"avg_cost_minor":250000,"ltp_minor":295000,"invested_minor":3750000,"value_minor":4425000,"pnl_minor":675000,"pnl_percent":18,"weight_percent":50.07,"source_count":2,"contributions":[{"source_id":"bconn_a1b2c3d4e5f60718","provider":"zerodha","quantity":10,"avg_cost_minor":250000,"value_minor":2950000},{"source_id":"bconn_b2c3d4e5f6071829","provider":"upstox","quantity":5,"avg_cost_minor":250000,"value_minor":1475000}]},{"key":"INF123K01014","asset_class":"mutual_fund","isin":"INF123K01014","symbol":null,"name":"Sample Liquid Fund - Growth","quantity":124.239,"avg_cost_minor":32198,"ltp_minor":35512,"invested_minor":4000250,"value_minor":4412035,"pnl_minor":411785,"pnl_percent":10.29,"weight_percent":49.93,"source_count":1,"contributions":[{"source_id":"cas_import","provider":"cas","quantity":124.239,"avg_cost_minor":32198,"value_minor":4412035}]}],"allocation":{"by_asset_class":[{"label":"equity","value_minor":4425000,"weight_percent":50.07,"holding_count":1},{"label":"mutual_fund","value_minor":4412035,"weight_percent":49.93,"holding_count":1}],"by_source":[{"label":"zerodha (live)","value_minor":2950000,"weight_percent":33.38,"holding_count":1},{"label":"upstox (live)","value_minor":1475000,"weight_percent":16.69,"holding_count":1},{"label":"Imported statement","value_minor":4412035,"weight_percent":49.93,"holding_count":1}],"concentration":{"top_holding":{"label":"RELIANCE","value_minor":4425000,"weight_percent":50.07,"holding_count":1},"top5_weight_percent":100,"hhi":5000,"effective_holdings":2}},"score":{"score":41.69,"band":"fair","factors":[{"id":"breadth","label":"Breadth","score":10,"weight":0.3,"note":"2 holding(s), 2 of them effective after weighting. 20 effective holdings scores full."},{"id":"concentration","label":"Concentration","score":0,"weight":0.3,"note":"Top 5 holdings are 100% of value; the largest alone is 50.07%. Lower is better. 40% top-5 and 10% single scores full."},{"id":"asset_mix","label":"Asset mix","score":100,"weight":0.2,"note":"2 asset class(es): equity 50.07%, mutual_fund 49.93%."},{"id":"standing","label":"Standing vs cost","score":93.47,"weight":0.2,"note":"Unrealized P&L is 14.02% on cost. A gain of 15% or better scores full. Structure only, not advice."}]},"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/portfolio/holdings":{"get":{"operationId":"portfolio-holdings","summary":"Deduplicated holdings","description":"The same stock held at three brokers comes back as ONE position, with a per-broker contributions breakdown. Filter to equity, mutual funds, ETFs or bonds.\n\nWhen asset_class is set, holdings and holding_count are filtered but totals still cover the whole portfolio.","tags":["Portfolio+"],"x-required-scope":"portfolio:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"connection_ids","in":"query","required":false,"description":"Comma-separated connection ids to include, such as bconn_a,bconn_b. Defaults to every active connection.","schema":{"type":"string"}},{"name":"include_cas","in":"query","required":false,"description":"Send false to leave the imported statement out and use broker accounts only. Defaults to true.","schema":{"type":"string"}},{"name":"asset_class","in":"query","required":false,"description":"Show only one class: equity, mutual_fund, etf, bond or other.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"as_of":"2026-11-07T09:30:00.000Z","holding_count":2,"totals":{"invested_minor":7750250,"value_minor":8837035,"pnl_minor":1086785,"pnl_percent":14.02,"holding_count":2,"source_count":3,"sources_ok":3,"sources_failed":0},"sources":[{"kind":"broker","id":"bconn_a1b2c3d4e5f60718","provider":"zerodha","label":"zerodha (live)","status":"ok","holding_count":1,"value_minor":2950000},{"kind":"broker","id":"bconn_b2c3d4e5f6071829","provider":"upstox","label":"upstox (live)","status":"ok","holding_count":1,"value_minor":1475000},{"kind":"cas","id":"cas_import","provider":"cas","label":"Imported statement","status":"ok","holding_count":1,"value_minor":4412035}],"holdings":[{"key":"INE123A01012","asset_class":"equity","isin":"INE123A01012","symbol":"RELIANCE","name":"RELIANCE","quantity":15,"avg_cost_minor":250000,"ltp_minor":295000,"invested_minor":3750000,"value_minor":4425000,"pnl_minor":675000,"pnl_percent":18,"weight_percent":50.07,"source_count":2,"contributions":[{"source_id":"bconn_a1b2c3d4e5f60718","provider":"zerodha","quantity":10,"avg_cost_minor":250000,"value_minor":2950000},{"source_id":"bconn_b2c3d4e5f6071829","provider":"upstox","quantity":5,"avg_cost_minor":250000,"value_minor":1475000}]},{"key":"INF123K01014","asset_class":"mutual_fund","isin":"INF123K01014","symbol":null,"name":"Sample Liquid Fund - Growth","quantity":124.239,"avg_cost_minor":32198,"ltp_minor":35512,"invested_minor":4000250,"value_minor":4412035,"pnl_minor":411785,"pnl_percent":10.29,"weight_percent":49.93,"source_count":1,"contributions":[{"source_id":"cas_import","provider":"cas","quantity":124.239,"avg_cost_minor":32198,"value_minor":4412035}]}],"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/portfolio/allocation":{"get":{"operationId":"portfolio-allocation","summary":"Allocation + concentration","description":"Weights by asset class and by broker, plus the concentration a plain P&L screen hides: largest holding, top-5 weight, HHI and effective holdings.","tags":["Portfolio+"],"x-required-scope":"portfolio:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"connection_ids","in":"query","required":false,"description":"Comma-separated connection ids to include, such as bconn_a,bconn_b. Defaults to every active connection.","schema":{"type":"string"}},{"name":"include_cas","in":"query","required":false,"description":"Send false to leave the imported statement out and use broker accounts only. Defaults to true.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"as_of":"2026-11-07T09:30:00.000Z","total_value_minor":8837035,"by_asset_class":[{"label":"equity","value_minor":4425000,"weight_percent":50.07,"holding_count":1},{"label":"mutual_fund","value_minor":4412035,"weight_percent":49.93,"holding_count":1}],"by_source":[{"label":"zerodha (live)","value_minor":2950000,"weight_percent":33.38,"holding_count":1},{"label":"upstox (live)","value_minor":1475000,"weight_percent":16.69,"holding_count":1},{"label":"Imported statement","value_minor":4412035,"weight_percent":49.93,"holding_count":1}],"concentration":{"top_holding":{"label":"RELIANCE","value_minor":4425000,"weight_percent":50.07,"holding_count":1},"top5_weight_percent":100,"hhi":5000,"effective_holdings":2},"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/portfolio/score":{"get":{"operationId":"portfolio-score","summary":"Portfolio score","description":"A 0-100 structural health score that always ships its own reasons: breadth, concentration, asset mix and standing, each with its weight and a plain-language note.\n\nWith no holdings the score is 0, band poor, with one factor explaining that there is nothing to score yet.","tags":["Portfolio+"],"x-required-scope":"portfolio:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"connection_ids","in":"query","required":false,"description":"Comma-separated connection ids to include, such as bconn_a,bconn_b. Defaults to every active connection.","schema":{"type":"string"}},{"name":"include_cas","in":"query","required":false,"description":"Send false to leave the imported statement out and use broker accounts only. Defaults to true.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"as_of":"2026-11-07T09:30:00.000Z","score":41.69,"band":"fair","factors":[{"id":"breadth","label":"Breadth","score":10,"weight":0.3,"note":"2 holding(s), 2 of them effective after weighting. 20 effective holdings scores full."},{"id":"concentration","label":"Concentration","score":0,"weight":0.3,"note":"Top 5 holdings are 100% of value; the largest alone is 50.07%. Lower is better. 40% top-5 and 10% single scores full."},{"id":"asset_mix","label":"Asset mix","score":100,"weight":0.2,"note":"2 asset class(es): equity 50.07%, mutual_fund 49.93%."},{"id":"standing","label":"Standing vs cost","score":93.47,"weight":0.2,"note":"Unrealized P&L is 14.02% on cost. A gain of 15% or better scores full. Structure only, not advice."}],"basis":{"holding_count":2,"source_count":3,"effective_holdings":2,"top5_weight_percent":100},"disclaimer":"Structural score only. Not investment advice, and no view on any instrument.","warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/emi/schedule":{"post":{"operationId":"emi-schedule","summary":"EMI / amortization","description":"Amortization schedule, EMI, total interest.\n\nThe last instalment is adjusted by a few paise so the balance ends at exactly 0.","tags":["Lending"],"x-required-scope":"lending:calc","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"principal_minor":{"type":"integer","description":"Loan amount in paise; above 0."},"annual_rate_pct":{"type":"number","description":"Interest rate in percent a year, from 0 to 100."},"months":{"type":"integer","description":"Number of monthly instalments, from 1 to 600."}},"required":["principal_minor","annual_rate_pct","months"]},"example":{"principal_minor":10000000,"annual_rate_pct":12,"months":12}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"emi_minor":3400221,"total_interest_minor":200664,"total_payment_minor":10200664,"schedule":[{"month":1,"emi_minor":3400221,"principal_minor":3300221,"interest_minor":100000,"balance_minor":6699779},{"month":2,"emi_minor":3400221,"principal_minor":3333223,"interest_minor":66998,"balance_minor":3366556},{"month":3,"emi_minor":3400222,"principal_minor":3366556,"interest_minor":33666,"balance_minor":0}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/fx/rates":{"get":{"operationId":"fx-rates","summary":"FX rates","description":"INR + cross-currency rates (FBIL/RBI-style).\n\nThese are reference rates. Do not use them where an official rate is required for accounting or regulatory purposes.\n\nShow the attribution text wherever you display the rates when the reply includes it.","tags":["Market Data"],"x-required-scope":"marketdata:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"base","in":"query","required":false,"description":"Three-letter currency code to quote against, for example INR or USD. Defaults to INR.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"base":"INR","rates":{"USD":0.012,"EUR":0.011,"GBP":0.0095,"JPY":1.85,"AED":0.044},"redistributable":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/marketdata/equity":{"get":{"operationId":"equity-quote","summary":"Equity quote","description":"LTP / OHLC / change% for a symbol.\n\nAn unknown symbol returns NOT_FOUND and is not charged.","tags":["Market Data"],"x-required-scope":"marketdata:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading symbol, 1 to 20 characters, for example RELIANCE.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"symbol":"RELIANCE","ltp_minor":295000,"open_minor":292659,"high_minor":296475,"low_minor":291781,"prev_close_minor":292659,"change_pct":0.8,"currency":"INR","redistributable":true}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/pms/performance":{"post":{"operationId":"pms-performance","summary":"PMS performance","description":"TWRR + XIRR from period values + cashflows.\n\nperiods[].start_value_minor and end_value_minor are required inside each period you send, as are date and amount_minor inside each cashflow.","tags":["PMS / AIF"],"x-required-scope":"pms:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","description":"Value of the portfolio at the start and end of each sub-period, in order. Start a new period at every deposit or withdrawal. Defaults to empty.","items":{"type":"object","properties":{"start_value_minor":{"type":"integer","description":"Value at the start of the period in paise. A period starting at 0 or below is skipped."},"end_value_minor":{"type":"integer","description":"Value at the end of the period in paise."}}}},"cashflows":{"type":"array","description":"Dated deposits and withdrawals, for the XIRR. Defaults to empty.","items":{"type":"object","properties":{"date":{"type":"string","description":"Date as YYYY-MM-DD."},"amount_minor":{"type":"integer","description":"Amount in paise: money put in is negative; money taken out, and the final value, are positive."}}}}}},"example":{"periods":[{"start_value_minor":1000000,"end_value_minor":1100000},{"start_value_minor":1100000,"end_value_minor":1210000}],"cashflows":[{"date":"2023-01-01","amount_minor":-1000000},{"date":"2024-01-01","amount_minor":1210000}]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"twrr":0.21,"xirr":0.21}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/vehicle/rc":{"post":{"operationId":"vehicle-rc","summary":"RC lookup","description":"VAHAN-style vehicle registration details.\n\nFields the registration record does not carry come back empty or are left out.","tags":["Vehicle / DL"],"x-required-scope":"vehicle:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rc_number":{"type":"string","description":"Vehicle registration number, 4 to 15 letters and digits, for example MH12AB1234. Case, spaces and hyphens are ignored."}},"required":["rc_number"]},"example":{"rc_number":"MH12AB1234"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"reg_no":"MH12AB1234","rto_code":"MH12","class":"Motor Car","chassis":"MA3EXAMPLE0012345","engine":"K12MN1234567","vehicle_manufacturer_name":"EXAMPLE MOTORS LTD","model":"EXAMPLE HATCHBACK VXI","vehicle_colour":"WHITE","vehicle_manufacturing_month_year":"03/2019","vehicle_category":"LMV","norms_type":"BHARAT STAGE VI","owner_count":"1","owner":"ASHA RAO","status":"ACTIVE","status_as_on":"2026-10-30","present_address":"12 Example Lane, Pune, Maharashtra, 411001","reg_authority":"PUNE","reg_date":"2019-04-12","rc_expiry_date":"2034-04-11","vehicle_tax_upto":"LTT","vehicle_insurance_upto":"2027-04-11","rc_financer":"","blacklist_status":"NA","is_commercial":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/vehicle/dl":{"post":{"operationId":"vehicle-dl","summary":"DL verify","description":"Sarathi-style driving-licence verification.","tags":["Vehicle / DL"],"x-required-scope":"vehicle:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dl_number":{"type":"string","description":"Driving licence number, 8 to 20 letters and digits; spaces and hyphens are ignored."},"dob":{"type":"string","description":"Date of birth, a past date as YYYY-MM-DD, DD/MM/YYYY or DD-MM-YYYY."}},"required":["dl_number","dob"]},"example":{"dl_number":"MH1220190001234","dob":"1990-01-01"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"dl_number":"MH1220190001234","dob":"17/08/1990","badge_details":[],"dl_validity":{"non_transport":{"from":"2019-05-10","to":"2039-08-16"},"transport":{"from":"","to":""},"hazardous_valid_till":"","hill_valid_till":""},"details_of_driving_licence":{"name":"ASHA RAO","father_or_husband_name":"RAMESH RAO","status":"ACTIVE","date_of_issue":"2019-05-10","date_of_last_transaction":"2019-05-10","address":"12 Example Lane, Pune, Maharashtra, 411001","split_address":{"district":["Pune"],"state":["Maharashtra"],"city":["Pune"],"pincode":"411001","country":["India"],"address_line":"12 Example Lane"},"cov_details":[{"cov":"LMV","issue_date":"2019-05-10"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/passport":{"post":{"operationId":"verify-passport","summary":"Verify passport","description":"Passport file number and date of birth checked against the passport record.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_number":{"type":"string","description":"Passport file number, 10 to 20 letters and digits; spaces and hyphens are ignored."},"dob":{"type":"string","description":"Date of birth, a past date as YYYY-MM-DD, DD/MM/YYYY or DD-MM-YYYY."}},"required":["file_number","dob"]},"example":{"file_number":"BO1065000012345","dob":"1990-08-17"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"file_number":"BO1065000012345","name":"ASHA RAO","given_name":"ASHA","surname":"RAO","dob":"17/08/1990","type_of_application":"Fresh","application_received_on_date":"02/01/2019"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/voter-id":{"post":{"operationId":"verify-voter-id","summary":"Verify voter ID","description":"EPIC number checked against the electoral record, with the voter's details.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"epic_number":{"type":"string","description":"EPIC number printed on the voter ID card, 6 to 20 letters, digits or slashes."}},"required":["epic_number"]},"example":{"epic_number":"ABC1234567"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"epic_number":"ABC1234567","name":"ASHA RAO","age":"36","gender":"F","relation_type":"FTHR","relation_name":"RAMESH RAO","address":"12 Example Lane, Pune, Maharashtra, 411001","split_address":{"district":["Pune"],"state":["Maharashtra"],"city":["Pune"],"pincode":"411001","country":["India"],"address_line":"12 Example Lane"},"state":"Maharashtra","assembly_constituency_no":"210","assembly_constituency":"Example Central","parliamentary_constituency_no":"34","parliamentary_constituency":"Example","part_no":"112","serial_no":"345","polling_station":"Example Primary School"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/mobile/otp":{"post":{"operationId":"verify-mobile-otp","summary":"Mobile ownership: send OTP","description":"Sends an OTP to the number and returns the reference_id, proving the person holds the number against the telco record.\n\nThis is step 1 of 2. The person receives the OTP on the number; call /v1/verify/mobile/otp/verify with the same mobile, this reference_id and the OTP to finish.\n\nEach call is charged separately. This proves the person holds the number against the telco record.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mobile":{"type":"string","description":"10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."}},"required":["mobile"]},"example":{"mobile":"9876543210"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"reference_id":"telecom_abc123"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/mobile/otp/verify":{"post":{"operationId":"verify-mobile-otp-verify","summary":"Mobile ownership: verify OTP","description":"Submits the OTP with the reference_id from the send call and returns the subscriber details.\n\nThis is step 2 of 2. Call /v1/verify/mobile/otp first to get the reference_id; the check fails if the OTP is wrong or has expired, and you can send a new OTP.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mobile":{"type":"string","description":"10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored. Must be the number the OTP was sent to."},"reference_id":{"type":"string","description":"The reference_id returned by /v1/verify/mobile/otp, 6 to 80 letters, digits, hyphens or underscores."},"otp":{"type":"string","description":"The OTP the person received, 4 to 8 digits."}},"required":["mobile","reference_id","otp"]},"example":{"mobile":"9876543210","reference_id":"telecom_abc123","otp":"123456"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"name":"ASHA RAO","address":"12 Example Lane, Pune, Maharashtra, 411001","split_address":{"district":["Pune"],"state":["Maharashtra"],"city":["Pune"],"pincode":"411001","country":["India"],"address_line":"12 Example Lane"},"mobile_number":"9876543210","country_code":"91","mobile_network_operator":"Example Telecom","billing_type":"Prepaid"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/mobile/silent":{"post":{"operationId":"verify-mobile-silent","summary":"Silent mobile check","description":"Checks a number against the telco record without sending an OTP.\n\nNo OTP is sent and the person does not have to do anything, so this does not prove they hold the number.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mobile":{"type":"string","description":"10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."}},"required":["mobile"]},"example":{"mobile":"9876543210"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"customer_name":"ASHA RAO","alternate_number":"","is_valid":"true","subscriber_status":"ACTIVE","connection_type":"PREPAID","current_service_provider":"Example Telecom","original_service_provider":"Example Telecom","network_region":"Maharashtra","is_ported":"false"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/mobile/mnrl":{"post":{"operationId":"verify-mobile-mnrl","summary":"Revoked-number check (MNRL)","description":"Whether the number is on DoT's Mobile Number Revocation List, with DoT's Financial Fraud Risk Indicator.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mobile":{"type":"string","description":"10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."}},"required":["mobile"]},"example":{"mobile":"9876543210"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"mnrl_check":{"match_found":false},"fri_check":{"match_found":false}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/icsi-membership":{"post":{"operationId":"verify-icsi","summary":"ICSI membership","description":"Company secretary membership (ACS or FCS) checked against the ICSI register.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"member_type":{"type":"string","description":"Membership class: ACS (associate) or FCS (fellow). Case is ignored."},"member_number":{"type":"string","description":"ICSI membership number, 1 to 7 digits."}},"required":["member_type","member_number"]},"example":{"member_type":"ACS","member_number":"41228"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"organization":"Example & Associates","type":"ACS","city":"Pune","address":"12 Example Lane, Pune, Maharashtra, 411001","split_address":{"district":["Pune"],"state":["Maharashtra"],"city":["Pune"],"pincode":"411001","country":["India"],"address_line":"12 Example Lane"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/electricity-bill":{"post":{"operationId":"verify-electricity-bill","summary":"Electricity bill (proof of address)","description":"Consumer name, address and latest bill from the electricity board. provider is the board code, e.g. MAHAVITRAN; installation_number and mobile are optional.\n\nOnly some boards are supported; an unsupported provider code is rejected and the call is refunded.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"Code of the electricity board, 2 to 40 letters, digits or underscores, for example MAHAVITRAN. Case and spaces are ignored."},"consumer_number":{"type":"string","description":"Consumer number printed on the bill, 3 to 30 letters, digits or slashes."},"installation_number":{"type":"string","description":"Installation number printed on the bill, 1 to 30 letters, digits or slashes; needed by some boards."},"mobile":{"type":"string","description":"Mobile number registered with the board. 10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."}},"required":["provider","consumer_number"]},"example":{"provider":"MAHAVITRAN","consumer_number":"123456789012"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"name":"ASHA RAO","address":"12 Example Lane, Pune, Maharashtra, 411001","split_address":{"district":["Pune"],"state":["Maharashtra"],"city":["Pune"],"pincode":"411001","country":["India"],"address_line":"12 Example Lane"},"consumer_no":"123456789012","electricity_provider":"MAHAVITRAN","tariff_code":"LT-I","consumption_units":"182","bill_no":"BL2026100123","bill_date":"2026-10-05","bill_due_date":"2026-10-20","bill_amount":"1480.00","amount_payable":"1480.00","due_amount":"0.00"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/bank-account/dynamic":{"post":{"operationId":"verify-bank-dynamic","summary":"Reverse penny drop: send amount","description":"Credits a small random amount to the account and returns a reference_id. The holder reports the amount back to prove they control the account. name and mobile are optional.\n\nThis is step 1 of 2. A small random amount is credited to the account. Ask the account holder what they received, then call /v1/verify/bank-account/dynamic/confirm with the referenceid and that amount.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_number":{"type":"string","description":"Bank account number, 6 to 20 digits."},"ifsc":{"type":"string","description":"IFSC of the branch: four letters, a zero, then six letters or digits."},"name":{"type":"string","description":"Account holder's name, 2 to 100 characters. When given, the name is matched against the bank's record."},"mobile":{"type":"string","description":"Account holder's mobile number. 10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."}},"required":["account_number","ifsc"]},"example":{"account_number":"123456782","ifsc":"HDFC0001234"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"referenceid":"ref_123456","active":"yes","reason":"","name_match":"yes","name_match_score":"100","mobile_match":"no","bank_transfer":{"response":"Success","bank_rrn":"612345678901","bene_name":"ASHA RAO","bene_ifsc":"HDFC0001234"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/verify/bank-account/dynamic/confirm":{"post":{"operationId":"verify-bank-dynamic-confirm","summary":"Reverse penny drop: confirm amount","description":"Checks the amount the account holder reports, in rupees, against the reference_id.\n\nThis is step 2 of 2 and needs the reference from /v1/verify/bank-account/dynamic. Each step is charged separately.","tags":["KYC / Identity"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference_id":{"type":"string","description":"The referenceid returned by /v1/verify/bank-account/dynamic, 6 to 80 letters, digits, hyphens or underscores."},"amount":{"type":"string","description":"The amount the account holder received, in rupees with up to two decimals, for example 1.05."}},"required":["reference_id","amount"]},"example":{"reference_id":"ref_123456","amount":"1.05"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"amount_match":"yes","ower_name":"ASHA RAO","mobile":"9876543210","mmid":"9123456"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/read/kyc-ocr":{"post":{"operationId":"read-kyc-ocr","summary":"KYC document OCR","description":"Extracts the fields from ID and utility documents. Send one or two images as public https URLs or base64.\n\nOnly the object for the detected document type is filled in; the others are absent or empty.\n\nImages given as URLs must be reachable from the public internet and must use https.","tags":["Document AI"],"x-required-scope":"read:document","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","description":"One or two images of the document, front and back if needed. Each item is a public https URL (up to 2040 characters) or base64 image data of at least 100 characters, with an optional data:...;base64, prefix.","items":{}}},"required":["documents"]},"example":{"documents":["https://example.com/kyc/pan-front.jpg"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"doc_type":"pan","status":"completed","completed_at":"2026-11-05T10:00:05Z","created_at":"2026-11-05T10:00:01Z","pan":{"name":"ASHA RAO","pan_number":"ABCDE1234F","dob":"17/08/1990"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/read/forgery":{"post":{"operationId":"read-forgery","summary":"Document forgery check","description":"Scores one or two document images (public https URLs) for tampering. threshold (0-100, default 20) sets the sensitivity; text_fields lets you check printed values.\n\nThe answer is returned in this reply; there is nothing to poll for later.","tags":["Document AI"],"x-required-scope":"read:document","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"type":"array","description":"One or two public https URLs of document images to check, each up to 2040 characters.","items":{}},"threshold":{"type":"integer","description":"Sensitivity from 0 to 100; defaults to 20. A lower number flags more images."},"text_fields":{"type":"object","description":"Printed values to compare with the image, as name and value pairs; names are 1 to 40 letters, digits or underscores and values up to 200 characters."}},"required":["urls"]},"example":{"urls":["https://example.com/kyc/pan-front.jpg"]}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"image_results":[{"copymove_detection":{"info":"No copy-move forgery found","score":0,"locations":[],"regions_of_concern":[]},"photocopy_detection":{"info":"Not a photocopy","score":"0.02"},"webcheck_detection":{"info":"Not found on the web","score":"0.01"},"screenshot_detection":{"info":"Not a screenshot","score":"0.03"},"splice_detection":{"info":"No splicing found","forged":"no","score":"0.04"}}],"image_correlation_results":{}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/business/udyam":{"post":{"operationId":"business-udyam","summary":"Udyam (MSME) verification","description":"Enterprise name, type, units, official address and NIC codes for a Udyam registration number, with the certificate PDF link.","tags":["Business / KYB"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"udyam_number":{"type":"string","description":"Udyam registration number in the form UDYAM-XX-00-0000000: state code, two digits, seven digits. Case and spaces are ignored; keep the hyphens."}},"required":["udyam_number"]},"example":{"udyam_number":"UDYAM-MH-19-0012345"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"general_info":{"udyam_registration_number":"UDYAM-MH-19-0012345","name_of_enterprise":"EXAMPLE TRADERS","type_of_enterprise":"Micro","major_activity":"Trading","organisation_type":"Proprietary","date_of_incorporation":"2019-06-01","date_of_udyam_registration":"2020-07-15"},"enterprise_type":[{"classification_year":"2024-25","enterprise_type":"Micro"}],"units_details":[{"unit_name":"Main unit","city":"Pune"}],"official_address_of_enterprise":{"flat_door_block_no":"12","road_street_lane":"Example Lane","city":"Pune","district":"Pune","state":"Maharashtra","pin":"411001"},"national_industry_classification_codes":[{"nic_code":"47190","activity":"Retail trade"}],"pdf_url":"https://example.com/udyam/certificate.pdf"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/business/udyam/otp":{"post":{"operationId":"business-udyam-otp","summary":"Udyam by OTP: send","description":"Sends an OTP to the enterprise's registered mobile and returns the request_id.\n\nThis is step 1 of 2. The OTP goes to the enterprise's registered mobile; call /v1/business/udyam/otp/verify with this request_id and the OTP to finish.\n\nThe request_id inside result is the OTP reference. It is separate from the request_id at the top of the reply, which identifies your API call.","tags":["Business / KYB"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"udyam_number":{"type":"string","description":"Udyam registration number in the form UDYAM-XX-00-0000000. Case and spaces are ignored; keep the hyphens."},"mobile":{"type":"string","description":"Mobile number registered on the Udyam record. 10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."}},"required":["udyam_number","mobile"]},"example":{"udyam_number":"UDYAM-MH-19-0012345","mobile":"9876543210"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"request_id":"udyam_otp_abc123"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/business/udyam/otp/verify":{"post":{"operationId":"business-udyam-otp-verify","summary":"Udyam by OTP: verify","description":"Submits the OTP with the request_id from the send call and returns the registration.\n\nThis is step 2 of 2 and needs the request_id from /v1/business/udyam/otp. If the OTP is wrong or has expired, the call fails and you can send a new OTP.","tags":["Business / KYB"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","description":"The request_id from /v1/business/udyam/otp, 6 to 80 letters, digits, hyphens or underscores."},"otp":{"type":"string","description":"The OTP received on the registered mobile, 4 to 8 digits."}},"required":["request_id","otp"]},"example":{"request_id":"udyam_otp_abc123","otp":"123456"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"name_of_enterprise":"EXAMPLE TRADERS","owner_name":"ASHA RAO","type_of_enterprise":"Micro","type_of_organisation":"Proprietary","major_activity":"Trading","pan":"ABCDE1234F","is_gstin_available":"No","date_of_incorporation":"2019-06-01","date_of_udyam_registration":"2020-07-15","official_address":{"city":"Pune","district":"Pune","state":"Maharashtra","pin_code":"411001"},"nic_code":[{"nic_code":"47190","activity":"Retail trade"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/business/tan":{"post":{"operationId":"business-tan","summary":"TAN verification","description":"Deductor details for a tax deduction account number (TAN).","tags":["Business / KYB"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tan":{"type":"string","description":"Tax deduction account number: four letters, five digits, one letter, for example HYDD01234A. Case and spaces are ignored."}},"required":["tan"]},"example":{"tan":"HYDD01234A"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"is_valid":"true","company_name":"EXAMPLE TRADERS"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/business/tin":{"post":{"operationId":"business-tin","summary":"TIN lookup","description":"Dealer details for an 11-digit state TIN.\n\nresult is a list, not an object; the field names above are for each item in it.","tags":["Business / KYB"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tin":{"type":"string","description":"Eleven-digit state TIN. Spaces and hyphens are ignored."}},"required":["tin"]},"example":{"tin":"27290123456"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":[{"dealer":"EXAMPLE TRADERS","owner_name":"ASHA RAO","pan":"ABCDE1234F","status":"Active","registration_status":"Registered","cst_status":"Registered","reg_date":"2015-04-01","cancel_date":"","address":"12 Example Lane, Pune, Maharashtra, 411001","split_address":{"district":["Pune"],"state":["Maharashtra"],"city":["Pune"],"pincode":"411001","country":["India"],"address_line":"12 Example Lane"}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/business/shop-establishment":{"post":{"operationId":"business-shop-establishment","summary":"Shop and establishment","description":"Registration details from the state record. States: Rajasthan, Uttar Pradesh, West Bengal, Jharkhand, Maharashtra (category required), Karnataka, Delhi.\n\nstate must be one of the seven listed; any other state is rejected and the call is refunded.","tags":["Business / KYB"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"registration_number":{"type":"string","description":"Registration number on the certificate, 3 to 40 letters, digits, slashes, dots, underscores or hyphens."},"state":{"type":"string","description":"State of registration: RAJASTHAN, UTTAR PRADESH, WEST BENGAL, JHARKHAND, MAHARASHTRA, KARNATAKA or DELHI. Case is ignored."},"category":{"type":"string","description":"Category printed on the certificate, for example COMMERCIAL ESTABLISHMENT (3 to 60 letters, spaces, & / or -). Required when state is MAHARASHTRA."}},"required":["registration_number","state"]},"example":{"registration_number":"2023/123/456","state":"KARNATAKA"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"establishment_name":"EXAMPLE TRADERS","registration_number":"2023/123/456","category":"COMMERCIAL ESTABLISHMENT","status":"Active","date_of_commencement":"2023-04-01","expiry_date":"2028-03-31","address":"12 Example Lane, Bengaluru, Karnataka, 560001","split_address":{"district":["Bengaluru Urban"],"state":["Karnataka"],"city":["Bengaluru"],"pincode":"560001","country":["India"],"address_line":"12 Example Lane"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/business/director":{"post":{"operationId":"business-director","summary":"Director search by DIN","description":"Director details and company associations from the MCA record for an 8-digit DIN.","tags":["Business / KYB"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"din":{"type":"string","description":"Director identification number, exactly 8 digits. Spaces and hyphens are ignored."}},"required":["din"]},"example":{"din":"03625470"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"din":"03625470","name":"ASHA RAO","father_name":"RAMESH RAO","dob":"1990-08-17","designation":"Director","date_of_appointment":"2018-05-02","address":"12 Example Lane, Pune, Maharashtra, 411001","split_address":{"district":["Pune"],"state":["Maharashtra"],"city":["Pune"],"pincode":"411001","country":["India"],"address_line":"12 Example Lane"},"whether_dsc_registered":"Yes","no_of_companies":"1","list_of_companies":[{"company_name":"EXAMPLE TRADERS PRIVATE LIMITED"}],"list_of_llps":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/employment/uan":{"post":{"operationId":"employment-uan","summary":"EPF employment history","description":"Employer-wise EPF history by UAN, by PAN with employee_name, or by mobile. dob is optional.\n\nLook up by uan, by pan together with employee_name, or by mobile; at least one of uan, pan or mobile is required.\n\nresult is a list, not an object; the field names above are for each item in it.","tags":["Employment"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"uan":{"type":"string","description":"Universal Account Number, 12 digits. Give this, or pan with employee_name, or mobile."},"pan":{"type":"string","description":"PAN of the employee, for example ABCDE1234F. When used, employee_name is required."},"employee_name":{"type":"string","description":"Employee's name, 2 to 100 characters. Required with pan."},"mobile":{"type":"string","description":"Mobile number linked to the EPF account. 10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."},"dob":{"type":"string","description":"Date of birth, a past date as YYYY-MM-DD, DD/MM/YYYY or DD-MM-YYYY."}}},"example":{"uan":"100123456789"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":[{"uan":"100123456789","name":"ASHA RAO","father_or_husband_name":"RAMESH RAO","member_id":"MHBAN00123450000012345","establishment_name":"EXAMPLE TECHNOLOGIES PRIVATE LIMITED","date_of_joining":"01-Feb-2019","date_of_exit":"31-Oct-2023"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/employment/employee-search":{"post":{"operationId":"employment-employee-search","summary":"Employee search in an establishment","description":"Whether a named employee appears in an EPFO establishment's records for a month (MM/YYYY).","tags":["Employment"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"establishment_id":{"type":"string","description":"The 15-character EPFO establishment ID, letters and digits."},"establishment_name":{"type":"string","description":"Name of the establishment, 2 to 200 characters."},"employee_name":{"type":"string","description":"Name of the employee to look for, 2 to 100 characters."},"employment_month":{"type":"string","description":"Month to search, as MM/YYYY, for example 02/2026."}},"required":["establishment_id","establishment_name","employee_name","employment_month"]},"example":{"establishment_id":"MHBAN0012345000","establishment_name":"ABC Pvt Ltd","employee_name":"Asha Rao","employment_month":"02/2026"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"match":true,"search_result":[{"establishment_name":"EXAMPLE TECHNOLOGIES PRIVATE LIMITED","establishment_id":"MHBAN0012345000","office_name":"BANGALORE","address":"12 Example Lane, Pune","payment_details":[{"date_of_credit":"14/03/2026","amount":"3,75,000","wage_month":"02/2026","ecr":"YES","employee_match":["ASHA RAO"],"trrn":"1234567890123"}]}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/employment/establishment":{"post":{"operationId":"employment-establishment","summary":"EPFO establishment details","description":"Establishment details with contribution summaries for the last 1 to 4 months.","tags":["Employment"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"establishment_id":{"type":"string","description":"The 15-character EPFO establishment ID, letters and digits."},"months":{"type":"integer","description":"How many recent months of contribution summary to return, 1 to 4."}},"required":["establishment_id","months"]},"example":{"establishment_id":"MHBAN0012345000","months":2}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"establishment_status":"Active","establishment_info":{"name_of_establishment":"EXAMPLE TECHNOLOGIES PRIVATE LIMITED","establishment_code":"MHBAN0012345000","ownership_type":"Private Limited Company","pan_status":"VERIFIED","date_of_setup_of_establishment":"01-JAN-2015","city":"Pune","state":"Maharashtra","pin_code":"411001","country":"India"},"transactions":{"monthly_summary":[{"salary_month":"SEP-2026","total_amount":"3750000","total_employees":"120","is_delay":"No","delay_in_day":"0"},{"salary_month":"AUG-2026","total_amount":"3700000","total_employees":"118","is_delay":"No","delay_in_day":"0"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/credit/bureau-report":{"post":{"operationId":"credit-bureau-report","summary":"Credit bureau report","description":"Credit bureau report by PAN, name, date of birth, mobile and pincode. The consumer's consent is required (given, timestamp, the IP they consented from); every pull is audited and fires a consumer alert.\n\nThe consumer's consent is required. Send consent.given as true, the time they consented and the IP address they consented from; a call without all three is rejected.\n\nEvery report pulled is audited and triggers a consumer alert, so only call this for a consumer who has agreed.","tags":["Credit"],"x-required-scope":"credit:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pan":{"type":"string","description":"PAN of the consumer, for example ABCDE1234F."},"first_name":{"type":"string","description":"First name, 1 to 60 characters."},"last_name":{"type":"string","description":"Last name, 1 to 60 characters."},"dob":{"type":"string","description":"Date of birth, a past date as YYYY-MM-DD, DD/MM/YYYY or DD-MM-YYYY."},"mobile":{"type":"string","description":"10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored."},"pincode":{"type":"string","description":"Six-digit pincode of the consumer's address; a number is also accepted."},"consent":{"type":"object","properties":{"given":{"type":"boolean","description":"Must be true."},"timestamp":{"type":"string","description":"When the consumer consented: an ISO 8601 time with offset, such as 2026-11-05T10:00:00+05:30, or a Unix time in seconds or milliseconds. It cannot be in the future."},"ip_address":{"type":"string","description":"The IPv4 or IPv6 address the consumer consented from."}},"required":["given","timestamp","ip_address"],"description":"The consumer's consent to the report being pulled."}},"required":["pan","first_name","last_name","dob","mobile","pincode","consent"]},"example":{"pan":"ABCDE1234F","first_name":"Asha","last_name":"Rao","dob":"1990-08-17","mobile":"9876543210","pincode":"411001","consent":{"given":true,"timestamp":"2026-11-05T10:00:00+05:30","ip_address":"203.0.113.10"}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"status_code":200,"message":"Success","data":{"json_bureau_report":{"header":{"system_code":0,"message_text":"Success","report_date":20261105,"report_time":100005},"credit_profile_header":{"report_date":20261105,"report_time":100005,"version":"V2.4","report_number":1234567},"cais_account":{"cais_summary":{"credit_account":{"credit_account_total":"5","credit_account_active":"4","credit_account_default":"0","credit_account_closed":"1"},"total_outstanding_balance":{"outstanding_balance_all":"450000"}},"cais_account_details":[{"subscriber_name":"EXAMPLE BANK","account_type":"10","open_date":20220115,"current_balance":120000,"amount_past_due":0}],"score":{"fcirexscore":742}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/tax/itr/fetch":{"post":{"operationId":"itr-fetch","summary":"ITR fetch","description":"Filed income-tax returns pulled with the taxpayer's own income-tax portal login. The password is passed through, never stored or logged.\n\nAt least one of password or session_id is required.\n\nThe password is passed straight through to the income-tax portal. It is never stored, logged or returned in the reply.","tags":["Income (ITR)"],"x-required-scope":"credit:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"The taxpayer's income-tax portal user ID, usually the PAN; 5 to 20 letters and digits, upper-cased for you."},"password":{"type":"string","description":"The taxpayer's income-tax portal password, up to 100 characters. Send this or session_id."},"session_id":{"type":"string","description":"A session ID from an earlier login, 6 to 300 characters. Send this or password."}},"required":["username"]},"example":{"username":"ABCDE1234F","password":"taxpayer-portal-password"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"2023-24":{"form":"ITR-1","json":{"itr":{}}},"2022-23":{"form":"ITR-1","json":{"itr":{}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/tax/itr/verify":{"post":{"operationId":"itr-verify","summary":"ITR-V verification","description":"Checks filed returns for the last 1 to 5 years (years, default 3) with the taxpayer's password or a session_id.\n\nAt least one of password or session_id is required.\n\nThe password is passed straight through and never stored, logged or returned.\n\nresult is a list, not an object; the field names above are for each item in it.","tags":["Income (ITR)"],"x-required-scope":"credit:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","description":"The taxpayer's income-tax portal user ID, usually the PAN; 5 to 20 letters and digits, upper-cased for you."},"password":{"type":"string","description":"The taxpayer's income-tax portal password, up to 100 characters. Send this or session_id."},"session_id":{"type":"string","description":"A session ID from an earlier login, 6 to 300 characters. Send this or password."},"years":{"type":"integer","description":"How many recent years to check, 1 to 5. Defaults to 3."}},"required":["username"]},"example":{"username":"ABCDE1234F","session_id":"sess_123456"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":[{"assessment_year":"2023-24","filing_year":"2023","pan_number":"ABCDE1234F","acknowledgement_number":"123456789012345","filing_type":"Original"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/risk/ip":{"post":{"operationId":"risk-ip","summary":"IP quality check","description":"Fraud score, proxy, VPN and Tor flags, ISP and location for an IPv4 or IPv6 address.","tags":["Risk & Location"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","description":"IPv4 or IPv6 address to check."}},"required":["ip"]},"example":{"ip":"203.0.113.10"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"fraud_score":"12","proxy":"false","vpn":"false","tor":"false","recent_abuse":"false","bot_status":"false","is_crawler":"false","mobile":"false","isp":"Example Broadband","organization":"Example Broadband","asn":"64500","host":"host.example.com","country_code":"IN","region":"Maharashtra","city":"Pune","latitude":"18.52","longitude":"73.85","timezone":"Asia/Kolkata","address":"203.0.113.10"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/risk/geo-fence":{"post":{"operationId":"risk-geo-fence","summary":"IP geo-fencing","description":"Whether an IP resolves inside the expected country (ISO code) and optional state, with its location.","tags":["Risk & Location"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","description":"IPv4 or IPv6 address to locate."},"country":{"type":"string","description":"Country you expect, as a two-letter ISO code such as IN. Case is ignored."},"state":{"type":"string","description":"State you expect, as a code of 1 to 3 letters or digits such as MH. Case is ignored."}},"required":["ip","country"]},"example":{"ip":"203.0.113.10","country":"IN","state":"MH"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"valid_user":true,"ip":"203.0.113.10","country":"India","country_code":"IN","state":"Maharashtra","state_code":"MH","city":"Pune","zip_code":"411001","timezone":"Asia/Kolkata","latitude":18.52,"longitude":73.85,"asn":"64500","riskip":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/geo/reverse-geocode":{"post":{"operationId":"geo-reverse-geocode","summary":"Reverse geocode","description":"Address, city, state and pincode for a latitude and longitude.","tags":["Risk & Location"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"latitude":{"type":"number","description":"Latitude from -90 to 90; a numeric string is also accepted."},"longitude":{"type":"number","description":"Longitude from -180 to 180; a numeric string is also accepted."}},"required":["latitude","longitude"]},"example":{"latitude":19.076,"longitude":72.8777}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"address":"12 Example Lane, Pune, Maharashtra 411001, India","city":"Pune","state":"Maharashtra","state_code":"MH","country":"India","country_code":"IN","zipcode":"411001","latitude":"18.5204","longitude":"73.8567","confidence_score":0.92}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/risk/negative-due-diligence":{"post":{"operationId":"risk-negative-due-diligence","summary":"Negative due diligence","description":"Screens an individual or entity against AML, CFT, non-compliance and lending watchlists: sanctions, PEP, defaulter and enforcement lists.\n\nAbout 50 further lists are returned in the same way, for example nse_defaulters, sfioconviction, irda_defaulters and eusanction_list. Each is a list that is empty when nothing matched.\n\nEvery item in a list has a scores object (name_match, dob_match, country_match and similar) and a details object describing the matching record.","tags":["Risk & Location"],"x-required-scope":"kyc:verify","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name of the person or entity to screen, 2 to 200 characters."},"type":{"type":"string","description":"Either individual or entity."},"categories":{"type":"array","description":"Which lists to search: any of AML, CFT, NONCOMPLIANCE and LENDING. Defaults to all four.","items":{}},"match_score_threshold":{"type":"number","description":"Lowest match score to report, from 0 to 1. Defaults to 0.5."},"country":{"type":"string","description":"Country to narrow the search, 2 to 60 characters. Defaults to INDIA."},"date_of_birth_or_incorporation":{"type":"string","description":"Date of birth, or date of incorporation for an entity, up to 20 characters."},"aliases":{"type":"array","description":"Other names the subject is known by; up to 20, each 1 to 200 characters.","items":{}}},"required":["name","type"]},"example":{"name":"Acme Traders","type":"entity"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"match_status":"no_match","general_watchlist":[],"sanction_list":[],"politically_exposed_person":[],"adverse_media":[],"enforcement":[],"mcadefaulter_entities":[],"mcadefaulter_directors":[],"fatf":[],"world_bank":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/vehicle/fastag/history":{"post":{"operationId":"vehicle-fastag-history","summary":"FASTag last location","description":"The most recent toll-plaza readings for a vehicle's FASTag.\n\nAn empty events list means the tag has not been read recently; it is not an error.","tags":["Vehicle / DL"],"x-required-scope":"vehicle:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicle_number":{"type":"string","description":"Vehicle registration number, 4 to 15 letters and digits, for example MH12AB1234. Case, spaces and hyphens are ignored."}},"required":["vehicle_number"]},"example":{"vehicle_number":"MH12AB1234"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"events":[{"reader_read_time":"2026-10-30 09:12:44","seq_no":"1","lane_direction":"N","toll_plaza_geocode":"19.0760,72.8777","toll_plaza_name":"EXAMPLE TOLL PLAZA","vehicle_type":"VC4","vehicle_reg_no":"MH12AB1234"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/vehicle/reverse-search":{"post":{"operationId":"vehicle-reverse-rc","summary":"Reverse RC search","description":"Registration details found from an engine_number or a chassis_number.\n\nSend at least one of engine_number and chassis_number; with neither, the call is rejected.","tags":["Vehicle / DL"],"x-required-scope":"vehicle:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"engine_number":{"type":"string","description":"Engine number, 5 to 25 letters and digits. Send this or chassis_number."},"chassis_number":{"type":"string","description":"Chassis number, 5 to 25 letters and digits. Send this or engine_number."}}},"example":{"chassis_number":"MA3EWDE1S00123456"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"reg_no":"MH12AB1234","rto_code":"MH12","class":"Motor Car","chassis":"MA3EXAMPLE0012345","engine":"K12MN1234567","vehicle_manufacturer_name":"EXAMPLE MOTORS LTD","model":"EXAMPLE HATCHBACK VXI","vehicle_colour":"WHITE","vehicle_manufacturing_month_year":"03/2019","vehicle_category":"LMV","norms_type":"BHARAT STAGE VI","owner_count":"1","owner":"ASHA RAO","status":"ACTIVE","status_as_on":"2026-10-30","present_address":"12 Example Lane, Pune, Maharashtra, 411001","reg_authority":"PUNE","reg_date":"2019-04-12","rc_expiry_date":"2034-04-11","vehicle_tax_upto":"LTT","vehicle_insurance_upto":"2027-04-11","rc_financer":"","blacklist_status":"NA","is_commercial":false}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/login/start":{"post":{"operationId":"broker-login-start","summary":"Broker login: start","description":"Step 1 of a hosted broker login: returns the broker's own login page to send your user to.\n\nStep 1 of 2. Send the user to redirect_url. After they log in, the broker sends them to your redirect_uri with query parameters.\n\nThen call login callback with state and those parameters within 10 minutes. A state can be used only once.\n\nA broker without a login page (for example angel, dhan, groww, shoonya, xts) is refused here; get its token from the broker and use connect with credentials.","tags":["Depository / Broker"],"x-required-scope":"broker:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"broker":{"type":"string","description":"Broker name, 2 to 30 characters. Hosted login works for zerodha, upstox, fyers, motilal, flattrade, zebu, tradesmart and arrow."},"api_key":{"type":"string","description":"Your API key with that broker, 1 to 200 characters."},"api_secret":{"type":"string","description":"Your API secret, 1 to 200 characters. Every broker that supports hosted login needs it; it is sealed inside state and never reaches the browser."},"redirect_uri":{"type":"string","description":"The URL on your side the broker returns the user to; a full URL up to 500 characters, registered with the broker."},"label":{"type":"string","description":"Your name for the connection that will be created, up to 80 characters."},"client_id":{"type":"string","description":"Broker client code, 1 to 100 characters; needed by motilal."}},"required":["broker","api_key","redirect_uri"]},"example":{"broker":"zerodha","api_key":"your_broker_api_key","api_secret":"your_broker_api_secret","redirect_uri":"https://app.example.com/broker/callback"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"broker":"zerodha","redirect_url":"https://broker.example.com/connect/login?v=3&api_key=your_broker_api_key&state=c3RhdGU","state":"c3RhdGVfZnJvbV9sb2dpbl9zdGFydA","expires_in_sec":600}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/login/callback":{"post":{"operationId":"broker-login-callback","summary":"Broker login: callback","description":"Step 2 of a hosted broker login: exchange what the broker sent back for a live connection.\n\nStep 2 of 2, after login start. The state must come from your own account, be under 10 minutes old and not have been used before.\n\nThe result is a live connection; use its connection_id on the other broker calls.","tags":["Depository / Broker"],"x-required-scope":"broker:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","description":"The state value from login start, unchanged; 1 to 4000 characters."},"params":{"type":"object","description":"Every query parameter the broker put on your redirect URL, as received (for example request_token or code); each value up to 2000 characters. Defaults to empty."}},"required":["state"]},"example":{"state":"state_from_login_start","params":{"request_token":"token_from_broker_redirect"}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"connection_id":"bconn_a1b2c3d4e5f60718","broker":"zerodha","mode":"live","label":"zerodha (live)","status":"connected"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/broker/profile":{"get":{"operationId":"broker-profile","summary":"Broker profile","description":"Client id, name and email of the account behind a broker connection.\n\nSend connection_id, or broker for a quick sandbox test. With neither, the call is refused.","tags":["Depository / Broker"],"x-required-scope":"broker:read","security":[{"bearerAuth":[]}],"parameters":[{"name":"connection_id","in":"query","required":false,"description":"The connection to use, as returned by connect (3 to 64 characters). Send this or broker.","schema":{"type":"string"}},{"name":"broker","in":"query","required":false,"description":"Quick sandbox test with no connection, by broker name (2 to 30 characters). One of: zerodha, angel, dhan, upstox, groww, motilal, fyers, shoonya, flattrade, xts, zebu, tradesmart, arrow. Send this or connection_id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"client_id":"AB1234","name":"ASHA RAO","email":"asha.rao@example.com","broker":"zerodha"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/import":{"post":{"operationId":"cas-import-upload","summary":"3.3 CAS Auto Import: upload and import","description":"Upload a statement PDF and import it into the portfolio in one call.\n\nSend as multipart/form-data, not JSON: the PDF in the file field and the other fields as form fields.\n\nA statement is always locked: send password (CAMS, KFintech) or pan (NSDL, CDSL) or the call is refused.\n\nReads the PDF and imports it in one call. Importing the next month's statement updates existing positions instead of adding duplicates.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:import","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The statement PDF, sent as the multipart form field named file. Up to 15 MB."},"password":{"type":"string","description":"The password chosen when the statement was requested (CAMS, KFintech); 1 to 64 characters. Send this or pan."},"pan":{"type":"string","description":"The investor's PAN, which opens NSDL and CDSL statements. Send this or password."},"dob":{"type":"string","description":"Date of birth as YYYY-MM-DD, for statements that need it."},"source":{"type":"string","description":"Who issued the statement, if you know it: kfintech, cams, nsdl or cdsl. Detected when left out."}},"required":["file"]},"example":{"password":"Sample@2026","source":"cams"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"import_id":"casim_1a2b3c4d5e6f7a8b","source":"cams","imported_at":"2026-11-06T09:30:00.000Z","holding_count":1,"created":1,"updated":0,"unchanged":0,"total_value_minor":4412035,"total_cost_minor":4000250,"total_gain_minor":411785,"xirr_percent":null,"holdings":[{"key":"mutual_fund:INF123K01014:1234567/89","kind":"mutual_fund","name":"Sample Liquid Fund - Growth","isin":"INF123K01014","folio":"1234567/89","units":124.239,"value_minor":4412035,"cost_minor":4000250,"gain_minor":411785,"as_of":"2024-03-31"}],"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/imports/{id}":{"get":{"operationId":"cas-import-get","summary":"3.3 CAS Auto Import: one import","description":"A past import run by its id, with the holdings it produced.\n\nAn unknown id returns NOT_FOUND.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:import","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The import_id returned by an import call.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"import_id":"casim_1a2b3c4d5e6f7a8b","source":"cams","imported_at":"2026-11-06T09:30:00.000Z","holding_count":1,"created":1,"updated":0,"unchanged":0,"total_value_minor":4412035,"total_cost_minor":4000250,"total_gain_minor":411785,"xirr_percent":null,"holdings":[{"key":"mutual_fund:INF123K01014:1234567/89","kind":"mutual_fund","name":"Sample Liquid Fund - Growth","isin":"INF123K01014","folio":"1234567/89","units":124.239,"value_minor":4412035,"cost_minor":4000250,"gain_minor":411785,"as_of":"2024-03-31"}],"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/read":{"post":{"operationId":"cas-read-upload","summary":"3.2 CAS Auto Read: upload","description":"Upload a statement PDF and get its folios, holdings and transactions as JSON.\n\nSend as multipart/form-data, not JSON: the PDF in the file field and the other fields as form fields.\n\nA statement is always locked: send password (CAMS, KFintech) or pan (NSDL, CDSL) or the call is refused.\n\nWhen review_required is true, have a person check the figures before relying on them.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:read","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The statement PDF, sent as the multipart form field named file. Up to 15 MB."},"password":{"type":"string","description":"The password chosen when the statement was requested (CAMS, KFintech); 1 to 64 characters. Send this or pan."},"pan":{"type":"string","description":"The investor's PAN, which opens NSDL and CDSL statements. Send this or password."},"dob":{"type":"string","description":"Date of birth as YYYY-MM-DD, for statements that need it."},"source":{"type":"string","description":"Who issued the statement, if you know it: kfintech, cams, nsdl or cdsl. Detected when left out."}},"required":["file"]},"example":{"password":"Sample@2026","source":"cams"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"source":"cams","statement_type":"detailed","investor_name":"ASHA RAO","investor_email":"asha.rao@example.com","pan":"******234F","period_from":"2023-04-01","period_to":"2024-03-31","holding_count":1,"transaction_count":1,"total_value_minor":4412035,"folios":[{"folio":"1234567/89","amc":"Sample Mutual Fund","scheme":"Sample Liquid Fund - Growth","isin":"INF123K01014","units":124.239,"nav_minor":35512,"value_minor":4412035,"cost_minor":4000250,"as_of":"2024-03-31"}],"demat":[],"transactions":[{"folio":"1234567/89","scheme":"Sample Liquid Fund - Growth","isin":"INF123K01014","date":"2023-06-12","description":"Purchase","type":"purchase","amount_minor":4000250,"units":124.239,"nav_minor":32198,"balance_units":124.239}],"confidence":0.97,"review_required":false,"warnings":[]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/requests":{"get":{"operationId":"cas-requests-list","summary":"3.1 CAS Auto Request: history","description":"Your most recent statement requests and what happened to each.\n\nA request marked submitted means the issuer accepted it. Delivery of the e-mail is not tracked.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:request","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"How many requests to return, newest first, from 1 to 100. Defaults to 20.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"requests":[{"request_id":"casrq_1a2b3c4d5e6f7a8b","source":"kfintech","status":"submitted","pan":"******234F","email":"asha.rao@example.com","statement_type":"detailed","period":"current_fy","from_date":null,"to_date":null,"rta_code":null,"message":"Your request has been received. The statement will be e-mailed shortly.","created_at":"2026-11-06T09:30:00.000Z","submitted_at":"2026-11-06T09:30:04.000Z"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/cas/requests/{id}":{"get":{"operationId":"cas-request-get","summary":"3.1 CAS Auto Request: one request","description":"The state of one statement request by its id.\n\nAn unknown id returns NOT_FOUND.","tags":["CAS (portfolio fetch)"],"x-required-scope":"cas:request","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The request_id of a statement request.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"request_id":"req_01HZY3K8M2","result":{"request_id":"casrq_1a2b3c4d5e6f7a8b","source":"kfintech","status":"submitted","pan":"******234F","email":"asha.rao@example.com","statement_type":"detailed","period":"current_fy","from_date":null,"to_date":null,"rta_code":null,"message":"Your request has been received. The statement will be e-mailed shortly.","created_at":"2026-11-06T09:30:00.000Z","submitted_at":"2026-11-06T09:30:04.000Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/wallet":{"get":{"operationId":"account-wallet","summary":"Wallet balance","description":"Your current prepaid wallet balance.\n\nThis reply is not wrapped in the usual request_id and result envelope; the fields are at the top level.\n\nAny valid API key can call this route.","tags":["Account"],"security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"tenant_id":"ten_0123456789abcdef0123456789abcdef","balance_minor":49000,"currency":"INR"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/usage":{"get":{"operationId":"account-usage","summary":"Usage history","description":"Your recent API calls: which route, when, how long it took and whether it succeeded.\n\nThis reply is not wrapped in the usual request_id and result envelope; the fields are at the top level.\n\nThe list holds your recent calls, not necessarily your whole history.","tags":["Account"],"security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"tenant_id":"ten_0123456789abcdef0123456789abcdef","total_calls":2,"events":[{"id":"evt_0123456789abcdef0123456789abcdef","tenant_id":"ten_0123456789abcdef0123456789abcdef","api":"POST /v1/verify/passport","units":1,"latency_ms":412,"success":true,"at":"2026-11-01T09:30:00.000Z"},{"id":"evt_fedcba9876543210fedcba9876543210","tenant_id":"ten_0123456789abcdef0123456789abcdef","api":"POST /v1/vehicle/dl","units":1,"latency_ms":380,"success":true,"at":"2026-11-01T09:31:12.000Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientBalance"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your Grappi API key."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"},"request_id":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"API key missing, invalid or revoked, or the caller's IP is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_api_key","message":"API key is invalid or revoked","request_id":"req_01HZY3K8M2"}}}}},"InsufficientBalance":{"description":"The wallet cannot cover this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_balance","message":"Prepaid wallet balance too low","request_id":"req_01HZY3K8M2"}}}}},"Forbidden":{"description":"The key lacks the required scope, or consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_scope","message":"Missing required scope","request_id":"req_01HZY3K8M2"}}}}},"NotFound":{"description":"No record matched. The check was carried out, so the call is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No record found for these details","request_id":"req_01HZY3K8M2"}}}}},"ValidationFailed":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"validation_failed","message":"Request validation failed","request_id":"req_01HZY3K8M2"}}}}},"RateLimited":{"description":"Too many requests. Slow down and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded","request_id":"req_01HZY3K8M2"}}}}},"Unavailable":{"description":"Temporarily unavailable. The call is refunded; retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"upstream_unavailable","message":"This API is temporarily unavailable. Try again shortly.","request_id":"req_01HZY3K8M2"}}}}}}}}