> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swippee.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports & transactions

> The StatementReport object, the transaction shape, and how to filter transactions.

A **report** is the result of parsing one statement. Everything else —
products, consents, enrichment — is derived from it.

## The StatementReport

```json theme={null}
{
  "report_id": "cl_abc123",
  "status": "complete",
  "statement": {
    "bank": "Nabil Bank",
    "bank_code": "NABIL",
    "currency": "NPR",
    "period": { "from": "2025-11-01", "to": "2026-04-30" },
    "opening_balance": 5028.73,
    "closing_balance": 5062.93,
    "total_transactions": 114
  },
  "signals": { },
  "monthly_summary": [ ],
  "categories": { },
  "merchant_categories": { "groceries": { "count": 12, "total": 8420 } },
  "transactions": [ ]
}
```

## The transaction object

Transactions follow a standard, industry-familiar shape.

| Field | Type | Description |
| - | - | - |
| `transaction_id` | string | Stable id within the report. |
| `date` | string | ISO 8601 (`YYYY-MM-DD`). |
| `name` | string | Raw narration as printed on the statement. |
| `amount` | number | **Signed: positive = money out (debit), negative = money in (credit).** |
| `iso_currency_code` | string | e.g. `NPR`. |
| `balance` | number \| null | Running balance after the transaction. |
| `merchant_name` | string \| null | Merchant parsed from the narration (or resolved from a Fonepay terminal). |
| `payment_terminal_id` | string \| null | Fonepay terminal PAN, when the rail carries one. |
| `mcc` | string \| null | ISO 18245 Merchant Category Code, when the merchant resolves. |
| `personal_finance_category` | object | `{ primary, detailed, confidence_level }` — two-level category + confidence. |
| `counterparties` | array | `[{ type, name, confidence_level }]` — who the money moved to/from. |
| `payment_channel` | string \| null | Not classified for parsed statements (`null`). |
| `pending` | boolean | Always `false` — statement lines are settled. |

## Filtering transactions

`GET /v1/reports/:id/transactions` takes query filters so you don't always need
the full set. Filters combine with **AND**.

```bash theme={null}
# only dining spend, debits, in April
curl "https://api.swippee.com/v1/reports/cl_abc123/transactions\
?merchant_category=dining&direction=debit&since=2026-04-01&until=2026-04-30&limit=100" \
  -H "Authorization: Bearer $SWIPPEE_API_KEY"
```

Filters: `category`, `merchant_category`, `direction` (credit | debit),
`since`, `until` (ISO dates), `limit` (default 500, max 1000).

## Provenance

Every report is stamped with how its data was obtained, so you know how far to
trust it:

| `data_source` | Meaning | `tamper_verifiable` |
| - | - | - |
| `PARSED_STATEMENT` | Parsed from the bank's own PDF/Excel | yes |
| `OCR_IMAGE` | Read from a photo/scan | **no** — upload the original PDF to verify |

## Listing & fetching

```bash theme={null}
# fetch one report
curl https://api.swippee.com/v1/reports/cl_abc123 \
  -H "Authorization: Bearer $SWIPPEE_API_KEY"

# list recent reports
curl 'https://api.swippee.com/v1/reports?limit=20&status=complete' \
  -H "Authorization: Bearer $SWIPPEE_API_KEY"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.