# Bank & reconciliation (https://docs.getbeel.com/en/api/bank-reconciliation)

Upload a bank statement, let the AI match its payments to your received invoices, then review the matches.

The same reconciliation as the app's **Reconciliations** page: Getbeel reads a bank statement, saves one transaction per movement and matches each payment to a received (supplier) invoice. You then confirm the matches, fix the wrong ones and see what is missing.

<Callout title="Live keys only for changes">
  Bank data is real: there is no sandbox for it. Test keys (`gb_test_…`) can
  read statements, transactions and matches; uploading and reviewing need a live
  key (`gb_live_…`), otherwise `403 livemode_required`. Each new movement of an
  uploaded statement costs €0.02 from the prepaid balance (`402
  insufficient_balance` when it does not cover it).
</Callout>

Scopes: `bank:read` to read, `bank:write` to upload and review.

## 1. Upload a statement [#1-upload-a-statement]

PDF, CSV or TXT, or a bank file: CBI (Italian RH flat file), CAMT.053 (ISO 20022 XML) or MT940; up to 50 MB (export a spreadsheet as CSV first). CBI, CAMT.053 and MT940 files are recognised by their content and read exactly, without AI; PDF and CSV are read with AI. Send the file as multipart:

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-statements \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@estratto-ottobre.csv" \
  -F "currency=EUR"
```

Requests are limited to about 4 MB. For larger files (up to 50 MB) put the file online and send JSON with `file_url` (public `https`, no redirects):

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-statements \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_url": "https://example.com/estratto-ottobre.pdf" }'
```

The answer is `202` with the statement in status `pending`. Processing runs in the background:

| Status       | Meaning                                                                |
| ------------ | ---------------------------------------------------------------------- |
| `pending`    | Queued                                                                 |
| `processing` | Reading the file                                                       |
| `parsed`     | Transactions saved (webhook `bank_statement.parsed`)                   |
| `matching`   | AI matching to received invoices                                       |
| `review`     | Done: the matches wait for review (webhook `reconciliation.completed`) |
| `completed`  | Marked as done in the app                                              |
| `failed`     | Could not be read: retry with `POST /reconciliations`                  |

`GET /bank-statements/{id}` also returns the bank, the period and the opening and closing balance (when the statement shows running balances).

## 2. Review the matches [#2-review-the-matches]

A reconciliation has the same id as its statement:

```bash
curl https://www.getbeel.com/api/v1/reconciliations/$STATEMENT_ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY"

curl "https://www.getbeel.com/api/v1/reconciliations/$STATEMENT_ID/matches?state=to_confirm" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Every transaction has one match. `match_type` is `exact`, `fuzzy` (check it), `manual` or `unmatched`, with a `confidence` from `0.00` to `1.00`. `state` says what to do:

| State               | Meaning                                                |
| ------------------- | ------------------------------------------------------ |
| `to_confirm`        | An invoice was found: approve or reject it             |
| `reconciled`        | Confirmed                                              |
| `missing_invoice`   | No invoice found for this payment                      |
| `no_invoice_needed` | Confirmed that it needs none (fees, taxes, transfers…) |
| `rejected`          | The suggestion was wrong                               |

Then:

- `POST /reconciliations/{id}/matches/{matchId}/approve`: the invoice is right (for a payment without invoice: none is needed).
- `POST /reconciliations/{id}/matches/{matchId}/reject`: the suggestion is wrong.
- `POST /reconciliations/{id}/matches` with `{ "transaction_id", "invoice_id" }`: link a received invoice by hand.
- `POST /reconciliations` with `{ "statement_id" }`: run reading and matching again (it replaces the transactions and matches).

## 3. What is missing [#3-what-is-missing]

- `GET /unmatched/payments`: money out with no invoice found, the documents to ask your suppliers for.
- `GET /unmatched/invoices`: received invoices no bank payment is matched to.

Both take `from` and `to` (`YYYY-MM-DD`) and the usual [pagination](/en/api/pagination). `GET /bank-transactions` lists every movement, with `statement_id`, `from`, `to` and `status` filters.

## With an AI assistant [#with-an-ai-assistant]

The [MCP server](/en/api/mcp) has `upload_bank_statement`, `get_bank_statement`, `get_reconciliation`, `list_unmatched`, `approve_match` and `match_manually`. The assistant asks you before every change.
