# Swippee

> Developer documentation for Swippee — Nepal's financial data layer. Convert Nepali bank statement PDFs into structured, machine-readable data, and read Nepal's public-sector financial datasets over a single REST API.

## Docs

- [Introduction](https://docs.swippee.com/introduction.md): Swippee turns Nepali bank statement PDFs into structured, machine-readable financial data — and serves Nepal's public-sector financial datasets — over one REST API.
- [Quickstart](https://docs.swippee.com/quickstart.md): Parse your first Nepali bank statement and read a product view in a few minutes.
- [Authentication](https://docs.swippee.com/authentication.md): How Swippee API keys, scopes, and bearer authentication work.
- [SDKs & client libraries](https://docs.swippee.com/guides/sdks.md): Official Swippee packages — the TypeScript API client (@swippee/sdk) and the React Connect component (@swippee/connect-react).
- [Reports & transactions](https://docs.swippee.com/concepts/reports.md): The StatementReport object, the transaction shape, and how to filter transactions.
- [Products](https://docs.swippee.com/concepts/products.md): The focused views you can derive from a parsed report — Income, Identity, Balance, Liabilities, Score, Verify, Underwriting.
- [Errors](https://docs.swippee.com/concepts/errors.md): Swippee's error envelope and the full error-code taxonomy.
- [Idempotency](https://docs.swippee.com/concepts/idempotency.md): Safely retry billable requests without creating duplicates or double-charging.
- [Webhooks](https://docs.swippee.com/concepts/webhooks.md): Receive parse results on your backend, with signed, retried delivery.
- [Sandbox](https://docs.swippee.com/guides/sandbox.md): Integrate end-to-end with synthetic data before sending a real statement.
- [Connect — embed the consumer Vault](https://docs.swippee.com/guides/connect.md): A hosted consent flow where the consumer approves which scopes you receive — your app never sees their statement or login.
- [Credit widget](https://docs.swippee.com/guides/credit-widget.md): Embed an in-app pre-qualification widget: the customer taps, consents, and gets an instant pre-qualified decision — powered by Swippee underwriting, the final call stays yours.
- [Consents — share a report safely](https://docs.swippee.com/guides/consents.md): Let a statement owner share a parsed report with a third party via a scoped, expiring token — without handing over an API key.
- [Merchant enrichment](https://docs.swippee.com/guides/merchant-enrichment.md): Resolve Fonepay terminal PANs and merchant-name strings to a clean name, MCC, spend category, and city.
- [Swippee Data API](https://docs.swippee.com/guides/data-api.md): Read-only access to Nepal's public-sector financial data — forex, interest rates, payments, macro — sourced from Nepal Rastra Bank with attribution.
- [Parse a bank statement](https://docs.swippee.com/api-reference/parsing/parse-a-bank-statement.md): Upload a Nepali bank statement (PDF, Excel, JPEG, or PNG, max 20 MB). Returns a full `StatementReport` with statement metadata, signals, monthly summary, categories, and every categorized transaction. Bills 1 unit.
- [List sandbox scenarios](https://docs.swippee.com/api-reference/sandbox/list-sandbox-scenarios.md): List the synthetic report scenarios and forced-error scenarios available in the sandbox. Requires a test key (`sk_test_…`).
- [Create a sandbox report](https://docs.swippee.com/api-reference/sandbox/create-a-sandbox-report.md): Create a deterministic, fully-synthetic `StatementReport` (or force a deterministic error). No file required. Report scenarios persist a `complete`, `test`-environment report, so every `/v1/reports/{id}/*` sub-endpoint works against the returned `report_id`. Requires a test key; never consumes quota…
- [Fire a sandbox webhook](https://docs.swippee.com/api-reference/sandbox/fire-a-sandbox-webhook.md): Trigger a webhook delivery for a sandbox report to your registered endpoints, on demand. Requires a test key; the report must belong to your organization.
- [List reports](https://docs.swippee.com/api-reference/reports/list-reports.md): List your organization's recent reports.
- [Get a report](https://docs.swippee.com/api-reference/reports/get-a-report.md): Fetch a single completed report by its ID.
- [List transactions](https://docs.swippee.com/api-reference/reports/list-transactions.md): The categorized transaction list for a report, with query filters. Filters combine with AND.
- [Income](https://docs.swippee.com/api-reference/products/income.md): Salary detection (amount, regularity, day-of-month), income_sources broken down by type (SALARY / REMITTANCE / INTEREST) with per-source totals + pay frequency, total_income, monthly credits, stability score, and the income transactions.
- [Identity](https://docs.swippee.com/api-reference/products/identity.md): Account holder, account number, bank, currency, and statement period — to confirm the uploader owns the account.
- [Auth (verified numbers)](https://docs.swippee.com/api-reference/products/auth-verified-numbers.md): The account's verified numbers — holder, account number, and the institution's SWIFT/BIC (only Class-A commercial banks in Nepal hold one; `swift_note` explains any absence) — plus a `verification_status` reflecting how the data was obtained.
- [Cash flow](https://docs.swippee.com/api-reference/products/cash-flow.md): Lender-grade cash-flow attributes: total + windowed (30/60/90d) inflow/outflow, net cash flow, average monthly balances, NSF/overdraft count, and the longest gap between transactions. Windows are measured back from the latest transaction date.
- [Recurring streams](https://docs.swippee.com/api-reference/products/recurring-streams.md): Recurring inflow + outflow streams (salary, rent, EMIs, subscriptions) with cadence, average amount, MATURE/EARLY_DETECTION status, whether the stream is still active, and a forecast next date. Built from real per-counterparty cadence.
- [Counterparties](https://docs.swippee.com/api-reference/products/counterparties.md): Who the money moved to/from: inflow/outflow split by counterparty type (merchant / individual / institution / wallet / cash / self) plus the top named people and merchants.
- [Trust (two-axis score)](https://docs.swippee.com/api-reference/products/trust-two-axis-score.md): A two-axis decision score: affordability (can they service the obligation) AND integrity (can the statement be trusted — tamper/forensics). Both 1–99, with integrity_basis, integrity_confidence, and an overall_band (ACCEPT | REVIEW | REJECT). Derived from data already on the report — not billed.
- [Name match](https://docs.swippee.com/api-reference/products/name-match.md): Verify the statement belongs to your applicant: send the claimed name, get a 0–100 match_score + banded result (match / partial_match / no_match) against the statement's account holder. Order-, initial-, honorific- and transliteration-tolerant. Names only — not full KYC.
- [Balance](https://docs.swippee.com/api-reference/products/balance.md): Opening/closing balances, average and minimum balance, and the balance trend.
- [Liabilities](https://docs.swippee.com/api-reference/products/liabilities.md): EMI/loan obligations bucketed by detected lender, monthly EMI total, EMI load %, and bounce count.
- [Score](https://docs.swippee.com/api-reference/products/score.md): A single 0–1000 creditworthiness score derived from the statement signals.
- [Verify](https://docs.swippee.com/api-reference/products/verify.md): Forgery/tamper detection — a verdict (authentic | review | suspicious), confidence, a derived risk_score (0–100) + risk_band + categorised risk_reasons, a risk_coverage flag (full when PDF forensics ran, else partial), and every check with pass/fail + severity.
- [Asset Report](https://docs.swippee.com/api-reference/products/asset-report.md): The full underwriting view — statement, signals, monthly summary, categories, and every transaction.
- [Underwriting](https://docs.swippee.com/api-reference/products/underwriting.md): Full lender decision: FOIR, disposable income, max supportable EMI, risk flags, and an approve/review/decline verdict. Bills 1 unit per call.
- [Enrich transactions](https://docs.swippee.com/api-reference/enrichment/enrich-transactions.md): Send raw transactions; get merchant, MCC, and spend category tags back. A transform endpoint — no report required.
- [List banks](https://docs.swippee.com/api-reference/banks/list-banks.md): List all banks and wallets Swippee knows about, with live NRB BFI data. READ_ONLY scope, no quota consumed.
- [Get a bank profile](https://docs.swippee.com/api-reference/banks/get-a-bank-profile.md): Full profile for one bank — SWIFT code, branch count, contact info, NRB paid-up capital, head office, and current Nepal market interest rates.
- [Resolve merchants](https://docs.swippee.com/api-reference/merchants/resolve-merchants.md): Turn raw Fonepay terminal PANs and merchant-name strings into clean merchant data — name, MCC, spend category, and city. FULL scope; bills 1 unit per call (batch up to 1000 lookups).
- [Resolve a merchant QR poster](https://docs.swippee.com/api-reference/merchants/resolve-a-merchant-qr-poster.md): Upload a Fonepay merchant QR poster (PDF or image) and get the merchant back — terminal, name, MCC, category, and city. We read the printed terminal and, for images, decode the QR. FULL scope; bills 1 unit per call. Max 10 MB.
- [Look up a terminal](https://docs.swippee.com/api-reference/merchants/look-up-a-terminal.md): Resolve a single Fonepay terminal PAN to its merchant.
- [List lending decisions](https://docs.swippee.com/api-reference/decisions/list-lending-decisions.md): List the decisions your organization has recorded. Filter with ?outcome=defaulted (etc.).
- [Record a lending decision](https://docs.swippee.com/api-reference/decisions/record-a-lending-decision.md): Closed-loop feedback: record the decision you made on an applicant, keyed by your own client_reference_id. Re-POSTing the same reference updates it (upsert).
- [Report a loan outcome](https://docs.swippee.com/api-reference/decisions/report-a-loan-outcome.md): The second half of the feedback loop — report what actually happened to a loan you recorded a decision on (same client_reference_id). Over time this trains the score on real results.
- [List issued statements](https://docs.swippee.com/api-reference/statements/list-issued-statements.md): List the verifiable statements your organization has issued. Each carries its tamper-evident content_hash (SHA-256 of the canonical statement) and a verify_url anyone can use to confirm authenticity. Scoped to your org. Filter with status=issued|revoked.
- [Get usage](https://docs.swippee.com/api-reference/account/get-usage.md): Check your quota and usage for the current month.
- [Create a Connect request](https://docs.swippee.com/api-reference/connect/create-a-connect-request.md): Your backend starts a hosted consent flow. Returns a request_token and connect_url to open in the browser.
- [Exchange a public token](https://docs.swippee.com/api-reference/connect/exchange-a-public-token.md): Exchange the public_token from a completed Connect flow for an access_token and grant_id.
- [List consent grants (audit)](https://docs.swippee.com/api-reference/connect/list-consent-grants-audit.md): List the consent grants this org holds — the consent + access trail for compliance / NRB auditability. Read-only, org-scoped. Returns consent metadata + access counts only; no consumer PII or tokens. Reading the granted data is the separate GET /v1/grants/{id}/data.
- [Consent grant + access audit trail](https://docs.swippee.com/api-reference/connect/consent-grant-+-access-audit-trail.md): One consent grant plus its full access audit trail (every read of the granted data: timestamp, scope, IP, user-agent). The bank/NRB-presentable consent record. Read-only, org-scoped; no consumer PII or tokens.
- [Read granted data](https://docs.swippee.com/api-reference/connect/read-granted-data.md): Read only the scopes the consumer granted. The access token goes in the X-Swippee-Access-Token header, never the URL. Optionally pass `?include=` to fetch only a subset of the granted scopes (data minimization) — the response is granted ∩ requested and can never exceed what was granted.
- [List consents](https://docs.swippee.com/api-reference/consents/list-consents.md)
- [Create a consent](https://docs.swippee.com/api-reference/consents/create-a-consent.md): Let the statement owner share a parsed report with a third party via a scoped, expiring token — without handing over an API key.
- [Redeem a consent](https://docs.swippee.com/api-reference/consents/redeem-a-consent.md): Grantee reads the shared data with the opaque token only — no API key required.
- [Revoke a consent](https://docs.swippee.com/api-reference/consents/revoke-a-consent.md)
- [Latest forex rates](https://docs.swippee.com/api-reference/data-—-nrb/latest-forex-rates.md): Latest buy/sell reference rates for all currencies. Counts against your Data API quota.
- [Forex series](https://docs.swippee.com/api-reference/data-—-nrb/forex-series.md): Daily series for one currency.
- [Convert currency](https://docs.swippee.com/api-reference/data-—-nrb/convert-currency.md): Convert an amount using the latest reference rate.
- [Banking snapshot](https://docs.swippee.com/api-reference/data-—-nrb/banking-snapshot.md): All C4 indicators for a month.
- [Banking indicators](https://docs.swippee.com/api-reference/data-—-nrb/banking-indicators.md): Flat indicator list for a month, filterable by BFI class.
- [Banking indicator series](https://docs.swippee.com/api-reference/data-—-nrb/banking-indicator-series.md): One indicator over time.
- [Latest interest rates](https://docs.swippee.com/api-reference/data-—-nrb/latest-interest-rates.md): All commercial-bank interest rates for the latest month.
- [Interest-rate series](https://docs.swippee.com/api-reference/data-—-nrb/interest-rate-series.md): One rate over time (base-rate, spread-rate, wavg-deposit, wavg-credit…).
- [Latest macro indicators](https://docs.swippee.com/api-reference/data-—-nrb/latest-macro-indicators.md): Latest report's indicators, each with a source quote.
- [Macro series](https://docs.swippee.com/api-reference/data-—-nrb/macro-series.md): One indicator over time (inflation, remittance, reserves, bop…).
- [Latest payment indicators](https://docs.swippee.com/api-reference/data-—-nrb/latest-payment-indicators.md): All channels (volume + value) for the latest month.
- [Payments series](https://docs.swippee.com/api-reference/data-—-nrb/payments-series.md): One channel/metric over time.
- [Licensed BFI directory](https://docs.swippee.com/api-reference/data-—-nrb/licensed-bfi-directory.md): Licensed banks and financial institutions, filterable by class.
- [Central Bank Survey — latest](https://docs.swippee.com/api-reference/data-—-nrb/central-bank-survey-—-latest.md): Nepal Rastra Bank's monthly balance sheet (foreign assets, claims on government / banks / private sector, reserve money) for the most recent month. From the IMF e-GDDS SDMX feed.
- [Central Bank Survey — series](https://docs.swippee.com/api-reference/data-—-nrb/central-bank-survey-—-series.md): One Central Bank Survey indicator over time.
- [Depository Corporations Survey — latest](https://docs.swippee.com/api-reference/data-—-nrb/depository-corporations-survey-—-latest.md): Nepal's consolidated monetary survey (broad money M1/M2, domestic credit, net foreign assets, money multipliers) for the most recent month.
- [Depository Corporations Survey — series](https://docs.swippee.com/api-reference/data-—-nrb/depository-corporations-survey-—-series.md): One monetary-survey indicator over time.
- [Consumer Price Index — latest](https://docs.swippee.com/api-reference/data-—-nrb/consumer-price-index-—-latest.md): Nepal's monthly CPI — overall index, COICOP groups, core, and ecological-belt breakdowns (2014/15=100).
- [Consumer Price Index — series](https://docs.swippee.com/api-reference/data-—-nrb/consumer-price-index-—-series.md): One CPI index over time.
- [Merchandise Trade — latest](https://docs.swippee.com/api-reference/data-—-nrb/merchandise-trade-—-latest.md): Nepal's monthly merchandise trade — total exports (FOB), imports (CIF), and the SITC-section breakdown.
- [Merchandise Trade — series](https://docs.swippee.com/api-reference/data-—-nrb/merchandise-trade-—-series.md): One trade aggregate over time.
- [Official Reserve Assets — latest](https://docs.swippee.com/api-reference/data-—-nrb/official-reserve-assets-—-latest.md): Nepal's monthly official reserve assets — total reserves, monetary gold (value + troy ounces), SDR holdings, IMF reserve position, foreign exchange.
- [Official Reserve Assets — series](https://docs.swippee.com/api-reference/data-—-nrb/official-reserve-assets-—-series.md): One reserve-asset line over time.
- [Banking balance sheet — latest](https://docs.swippee.com/api-reference/data-—-nrb/banking-balance-sheet-—-latest.md): Consolidated statement of assets & liabilities for Nepal's whole banking system (commercial + development + finance) — every line item, latest month. Values in NPR millions.
- [Banking balance sheet — series](https://docs.swippee.com/api-reference/data-—-nrb/banking-balance-sheet-—-series.md): One balance-sheet line item over time.
- [Banking profit & loss — latest](https://docs.swippee.com/api-reference/data-—-nrb/banking-profit-&-loss-—-latest.md): Consolidated profit & loss for Nepal's whole banking system — interest income/expense, net interest income, fees, operating profit, provisions, net profit. NPR millions.
- [Banking profit & loss — series](https://docs.swippee.com/api-reference/data-—-nrb/banking-profit-&-loss-—-series.md): One P&L line item over time.
- [Banking sector credit — latest](https://docs.swippee.com/api-reference/data-—-nrb/banking-sector-credit-—-latest.md): Loans & advances of Nepal's whole banking system, broken down by economic sector and by product. NPR millions.
- [Banking sector credit — series](https://docs.swippee.com/api-reference/data-—-nrb/banking-sector-credit-—-series.md): One sector or product line over time.
- [Per-bank balance sheet — latest](https://docs.swippee.com/api-reference/data-—-nrb/per-bank-balance-sheet-—-latest.md): Statement of assets & liabilities for each individual bank & financial institution in Nepal. Use `?bank=` to scope to one. NPR millions.
- [Per-bank balance sheet — series](https://docs.swippee.com/api-reference/data-—-nrb/per-bank-balance-sheet-—-series.md): One institution's balance-sheet line item over time.
- [Per-bank profit & loss — latest](https://docs.swippee.com/api-reference/data-—-nrb/per-bank-profit-&-loss-—-latest.md): Profit & loss for each individual bank & financial institution in Nepal. Use `?bank=` to scope to one. NPR millions.
- [Per-bank profit & loss — series](https://docs.swippee.com/api-reference/data-—-nrb/per-bank-profit-&-loss-—-series.md): One institution's P&L line item over time.
- [Per-bank sector credit — latest](https://docs.swippee.com/api-reference/data-—-nrb/per-bank-sector-credit-—-latest.md): Loans & advances by economic sector for each individual bank & financial institution in Nepal. Use `?bank=` to scope to one. NPR millions.
- [Per-bank sector credit — series](https://docs.swippee.com/api-reference/data-—-nrb/per-bank-sector-credit-—-series.md): One institution's sector line over time.

## OpenAPI Specs

- [openapi](https://docs.swippee.com/openapi.json)