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

# Bank Accounts, Balances and Transactions: Data Model

> The Bank data model: accounts with stable ids, typed balances, booked and pending transactions, and a change feed with a durable cursor.

Didit's Bank data API stores each connection's accounts, balances and transactions and serves them through read endpoints with pagination (`cursor` on lists, `page_token` on the transaction reads).
Amounts are decimal strings with a separate ISO 4217 `currency`, dates are ISO 8601, and countries are ISO alpha-3.
Reads never bill.

## Accounts

`GET /v3/bank/connections/{id}/accounts/` lists the accounts of a connection, and `GET /v3/bank/accounts/{account_id}/` returns one.

| Field | Meaning |
| - | - |
| `id` | Belongs to the connection and never changes while it exists, renewals included. |
| `account_ref` | Identifies the same bank account across connections of one application and environment. It is a keyed hash of the bank's own identifiers, and `null` when the bank gives no reliable identifier. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` or `other`, and `personal`, `business` or `unknown`. |
| `identifiers` | The IBAN, BIC and other identifiers. Server-side callers with the bank data permission receive them in full. |
| `holders[]` | Each holder with a `name` and a `role`: `holder`, `joint_holder`, `representative` or `unknown`. |
| `sync.last_synced_at` | When Didit last fetched the data from the bank, not when you last read it. |
| `history_coverage` | What the bank delivered of the history you asked for: `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` and a `status` of `complete`, `partial`, `empty`, `unavailable` or `unknown`. |

Use `account_ref` to recognise a bank account when a person connects it again, and `id` for everything inside one connection.

## Balances

`GET /v3/bank/accounts/{account_id}/balances/` returns typed balances with their reference dates.

```json theme={null}
{
  "account_id": "a71f0c2e-...",
  "balances": [
    { "type": "booked", "amount": "18250.34", "currency": "EUR", "reference_date": "2026-11-20" },
    { "type": "available", "amount": "17990.34", "currency": "EUR", "reference_date": "2026-11-21" }
  ],
  "last_synced_at": "2026-11-21T12:04:40Z"
}
```

`type` is `booked`, `available` or `expected`, and `iso_type` carries the bank's ISO 20022 code where the bank gives one.

## Transactions

`GET /v3/bank/accounts/{account_id}/transactions/` reads a date range.
It takes `date_from` and `date_to` (calendar dates as the bank reports them, inclusive), `status` (`booked` or `pending`, both by default), `limit` (up to 500) and `page_token`.
It sorts by `effective_date` descending, then `id`.

```json theme={null}
{
  "id": "8f2b...",
  "status": "booked",
  "booking_date": "2026-11-19",
  "value_date": "2026-11-20",
  "amount": "-1210.00",
  "currency": "EUR",
  "direction": "debit",
  "description": "RECIBO SEGURIDAD SOCIAL",
  "counterparty": { "name": "TESORERIA GENERAL SEG SOCIAL", "iban": "ES7620770024003102575766" },
  "remittance": { "unstructured": ["RECIBO SEGURIDAD SOCIAL 10/2026"], "reference": "0028123456789" },
  "bank_transaction_code": "PMNT-RDDT-ESDD",
  "bank_reference": "2026111900012345",
  "identity_quality": "bank_reference",
  "balance_after": "18250.34",
  "category": "taxes_and_social_security"
}
```

* **`id`** is Didit's, stored at first sight. The same movement keeps its id across reads, syncs and renewals.
* **`identity_quality`** says how strong that guarantee is. `bank_reference` and `route_id` are stable. `derived` means the movement was matched by its content, so a bank correction can appear as one `removed` and one `added`.
* **`status`** is `booked` or `pending`. A pending transaction has its own id. When the bank books it, the booked transaction arrives as `added`, the pending one as `removed` with `reason: pending_booked`, and `pending_id` is set only where the bank links them.
* **`amount`** is signed: negative is money out. `direction` repeats the sign.
* **`bank_reference`** is the bank's immutable entry reference, `null` where the bank does not provide one. Didit never invents it.
* **`category`** is Didit's own categorisation, when one applies.
* A correction by the bank to a booked transaction is `modified`. A reversal is a new transaction, with `reverses_id` when the bank links it.

### Fields a bank does not send are null

Every field a bank does not send is `null`.
The institution lists the fields it is known to send in `transaction_fields`, together with `pending_transactions`, `pending_linkage`, `balance_types` and `history_days_max`, so nobody discovers gaps in production.
Use the `sparse_fields` test customer in the [sandbox](https://docs.didit.me/core-technology/bank-verification/sandbox.md) to test your code against a bank that sends little.

### Paging a date range

Keep reading with `page_token` while `has_more` is true.
The token pins the read's snapshot for one hour: additions after the first page are not in it, each row is served in its current state, and a row removed during paging drops out of later pages and shows up in the change feed.
An expired token answers `410 page_expired`: restart the read from its original query.

## The change feed

`GET /v3/bank/connections/{id}/transactions/sync/` returns what changed across all accounts of a connection since a `cursor`.

```json theme={null}
{
  "added": [ { "id": "...", "status": "booked", "amount": "-35.00" } ],
  "modified": [],
  "removed": [ { "id": "...", "reason": "pending_booked" } ],
  "has_more": false,
  "next_cursor": "...",
  "reset": false
}
```

* An empty cursor returns every current transaction as `added` with `reset: true`. Replace your copy with it instead of adding to it.
* Keep paging with `page_token` while `has_more` is true. Store `next_cursor` only after a response with `has_more: false`, and if paging fails midway restart from the cursor you stored.
* A cursor is opaque and bound to the connection and the environment. The change log is replayable for 90 days. An older cursor answers `410 cursor_expired` with `bootstrap: true`: start again from an empty cursor and replace your copy.
* `removed[].reason` is `pending_booked`, `pending_expired`, `bank_removed` or `access_removed`.

The step by step version is in [Continuous bank feed for accounting](https://docs.didit.me/use-cases/bank-data-for-accounting.md).

## Headers

Both transaction reads return the `X-RateLimit-*` headers (600 reads and 300 writes per minute per application, 429 with `Retry-After` beyond that) and `X-Bank-Last-Synced-At`.
API limits and the bank's own limits on fetching are separate things: see [Refresh bank data on demand](https://docs.didit.me/use-cases/refresh-bank-data-on-demand.md).


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