# Bank transactions

Read the bank lines on your company's bank accounts over the LedgerBee public
API (base URL [`https://api.ledgerbee.com/api/v1`](https://api.ledgerbee.com/api/v1)).
A bank line is one movement the bank reported: money in or out, with the text
and counterparty the bank sent. Authenticate with the `x-api-key` header.
There are two scopes:

- `bank-transactions-read` lists and reads lines.
- `bank-reconciliations-write` dismisses a line from reconciliation, restores
  it, and reconciles lines against entries. It does not grant the reads.

## Operations

| Operation | Endpoint | Scope |
| --- | --- | --- |
| List bank lines | `GET /v1/bank-transactions` | `bank-transactions-read` |
| Get a bank line | `GET /v1/bank-transactions/{bankTransactionId}` | `bank-transactions-read` |
| Dismiss lines (and preview) | `POST /v1/bank-transactions/dismiss`, `POST /v1/bank-transactions/dismiss/preview` | `bank-reconciliations-write` |
| Restore dismissed lines (and preview) | `POST /v1/bank-transactions/undismiss`, `POST /v1/bank-transactions/undismiss/preview` | `bank-reconciliations-write` |
| Reconcile lines against entries | `POST /v1/bank-reconciliations` | `bank-reconciliations-write` |

Endpoint schemas are in the [API Reference](/api).

```bash
curl 'https://api.ledgerbee.com/api/v1/bank-transactions?status=open&bookingDateFrom=2026-01-01' \
  -H 'x-api-key: <your-key>'
```

## Amounts and currencies

Each line states its amount in the bank account's own currency, and, when the
bank reports one, the amount in the currency the payment was made in.

| Field | Holds |
| --- | --- |
| `bankAccountAmount` | The amount in `bankAccountCurrency`, the bank account's currency. Negative for money out, positive for money in. |
| `originalAmount` | The amount in `originalCurrency`, such as a card purchase abroad, with the same sign as `bankAccountAmount`. On a line whose `bankAccountAmount` is 0 it is the figure as the bank sent it, which may carry either sign. `null` when the bank reports none. |
| `originalExchangeRate` | The rate the bank converted at, as it reports it. `null` when it reports none. |
| `direction` | `INCOMING` or `OUTGOING`, from the sign of `bankAccountAmount`. `null` on a zero-amount line. |

A bank account kept in EUR states its lines in EUR. Add `bankAccountAmount`
values together only within one `bankAccountCurrency`.

## Reconciliation state

`status` says where a line stands. Exactly one applies:

| `status` | Meaning | What the line carries |
| --- | --- | --- |
| `open` | Waiting to be reconciled. | `reconciliation: null`, `dismissedAt: null` |
| `reconciled` | Matched to entries. | `reconciliation` with the `reconciliationId`, the booked `journalEntryIds`, the `draftJournalEntryIds` not booked yet, and the `openEntryId` of the invoice or bill the line settled directly, as the open-entries listing reports it. |
| `dismissed` | Taken off reconciliation because it needs no match, such as a duplicate the bank delivered twice. | `dismissedAt`, the time it was dismissed, or `null` when that time was not recorded. |

Undo a reconciliation with `POST /v1/bank-reconciliations/{reconciliationId}/unreconcile`,
which puts the line back to `open`. Restoring a dismissed line puts it back to
`open` and clears `dismissedAt`.

## Listing and paging

The list returns the lines on your company's bank accounts, including disabled
ones, newest booking first. Lines on a deleted bank account are left out.

| Query parameter | Effect |
| --- | --- |
| `bankAccountId` | Only lines on this bank account. |
| `bookingDateFrom`, `bookingDateTo` | Only lines the bank booked within these dates (`YYYY-MM-DD`), both inclusive. |
| `bankAccountAmountMin`, `bankAccountAmountMax` | Only lines whose signed `bankAccountAmount` is within these bounds, both inclusive. `bankAccountAmountMin=-500&bankAccountAmountMax=-100` selects payments out of 100 to 500. |
| `status` | `open`, `reconciled` or `dismissed`. |
| `sortBy`, `sortOrder` | `bookingDate` (default) or `bankAccountAmount`; `DESC` (default) or `ASC`. Lines that tie are ordered by id. |
| `limit` | Lines per page, 1 to 100. Default 25. |
| `cursor` | The previous page's `nextCursor`. |

Each page carries `total` (lines matching the query across all pages),
`hasMore`, and `nextCursor`. Page by sending `nextCursor` back as `cursor` with
the same filters and sort, until `hasMore` is `false`. `page` is still accepted
and is deprecated; see [Pagination](/guides/pagination).

```bash
curl 'https://api.ledgerbee.com/api/v1/bank-transactions?limit=100&cursor=<nextCursor>' \
  -H 'x-api-key: <your-key>'
```

## Errors

| Condition | What you observe | Fix |
| --- | --- | --- |
| The key lacks the scope the operation needs | `403 INSUFFICIENT_PERMISSIONS` | Add `bank-transactions-read` to read, or `bank-reconciliations-write` to change a line. |
| The line does not exist, belongs to another company, or is on a deleted bank account | `404 BANK_TRANSACTION_NOT_FOUND` | Look the line up again with the list. |
| `bankAccountAmountMin` is greater than `bankAccountAmountMax` | `400 BANK_INVALID_AMOUNT_RANGE` | Swap the bounds. |
| `bookingDateFrom` or `bookingDateTo` is not a `YYYY-MM-DD` date that exists, such as `2026-02-30` | `400 SHARED_VALIDATION_FAILED` | Send a real calendar date in `YYYY-MM-DD` form. |
| A `cursor` is sent with other filters or another sort than the request that produced it | `400 PAGINATION_INVALID_CURSOR` | Start again without `cursor`, or send the original filters. |
| `cursor` and `page` are sent together | `400 PAGINATION_CURSOR_WITH_PAGE` | Send only `cursor`. |