> ## 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"
```