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

Automatic bank transactions through Enable Banking, using your company's own Enable Banking application.

Getbeel downloads your bank account movements every 6 hours and matches them to invoices, as if a statement arrived every month. The connection goes through [Enable Banking](https://enablebanking.com) with **your own Enable Banking application**: you register it in your company's name, and Getbeel signs the calls with its private key.

Scopes: `bank:read` to read, `bank:write` to connect, reconnect, sync and disconnect. Reads work with any key; changes need a live key (`403 livemode_required`). Each connected account costs €2 a month and each imported movement €0.02, from the prepaid balance (`402 insufficient_balance` when it does not cover them).

## Before you start [#before-you-start]

1. Create an account at [Enable Banking](https://enablebanking.com/sign-in/).
2. In the [control panel](https://enablebanking.com/cp/applications) register an application in the **Production** environment (or **Sandbox** to try it with the "Mock ASPSP" test bank). Choose "Generate in the browser" and export the `.pem` private key.
3. Under "Allowed redirect URLs" add exactly:

   ```text
   https://getbeel.com/api/open-banking/callback
   ```

4. Activate the application with "Activate by linking accounts": in restricted mode the application only reads the accounts linked there.

<Callout type="warn">
  Enable Banking describes restricted mode as meant for evaluation and
  "individual non-commercial use". Check with Enable Banking that your use fits
  their terms, or sign a contract with them.
</Callout>

## Connect a bank [#connect-a-bank]

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-connections \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @- <<EOF
{
  "application_id": "aaaaaaaa-1111-2222-3333-444444444444",
  "private_key": "$(awk '{printf "%s\\n", $0}' private.pem)",
  "bank": { "name": "Intesa Sanpaolo", "country": "IT" },
  "psu_type": "business"
}
EOF
```

Getbeel checks the key with a real call, stores it encrypted (it is never returned) and starts the bank login. Response `201`:

```json
{
  "object": "bank_connection",
  "id": "5b0c…",
  "status": "pending",
  "bank": { "name": "Intesa Sanpaolo", "country": "IT" },
  "authorization_url": "https://getbeel.com/bank-login?t=…",
  "redirect_url_registered": true,
  "accounts": []
}
```

Open `authorization_url` in a browser. It is a Getbeel page that names your team, so the person who logs in sees whose team gets their accounts; **Continue** takes them to the bank. There they allow reading the accounts (up to 180 days, depending on the bank), then land in the Getbeel app. The first sync (last 90 days) starts right away. The bank name is the one in Enable Banking's list (`GET /aspsps` with your application, or the picker in the app).

Errors: `422 bank_credentials_invalid` (id or key refused), `422 redirect_url_not_allowed` (step 3 is missing), `409 bank_connection_limit` (at most 10 banks per team).

## List and status [#list-and-status]

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

`status`: `pending` (bank login not finished), `active`, `requires_reconnect` (consent expired or revoked). `consent_expires_at` and `expires_soon` (under 7 days) tell when to [reconnect](#reconnect). Each account has its IBAN, balance, number of synced transactions and `pending_transactions` (see below).

## Reconnect [#reconnect]

Banks ask for the consent again at least every 180 days (PSD2; often sooner, depending on the bank). Seven days before it ends Getbeel emails the team owners, sends the `bank_connection.expiring` webhook and shows a banner with a Reconnect button in Reconciliation; when it has ended (or the bank revoked it) it does the same with `bank_connection.expired`, once per consent. Both webhooks carry the `BankConnection` and go to live endpoints only.

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-connections/$ID/reconnect \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "en" }'
```

The response is the connection with a new `authorization_url` (valid 30 minutes): open it in a browser and log in to the bank again. The old consent is closed, the accounts are found again (same IBANs, same monthly statements) and a sync starts right away. The body is optional. Errors: `409 bank_connection_conflict` (no bank chosen yet), the same `422` as connecting, `402 insufficient_balance` when the balance does not cover the account month.

## Where the transactions go [#where-the-transactions-go]

For each account and month Getbeel creates a statement with `source: "open_banking"` (in `GET /bank-statements`), without a file. Each sync adds the new booked transactions, without duplicates, and matches only the new ones to invoices. You get the `bank_statement.parsed` webhook (transactions added) and then `reconciliation.completed`. Transactions are in `GET /bank-transactions` and in the matches, as for uploaded statements.

**Pending movements.** Movements the bank has not booked yet (Enable Banking status `PDNG`, the ISO 20022 entry status for pending entries) are not transactions: they are listed per account in `pending_transactions` (newest 50, signed amounts), are never matched and are replaced at every sync. Once the bank books one, it arrives in `GET /bank-transactions` like any other.

**Supplier and autofattura.** Before matching, each new outgoing transaction gets the same AI fields as uploaded statements: supplier country, VAT number and address when known, whether it is foreign, and whether it needs an autofattura (TD17, TD18 or TD19), so foreign suppliers paid from a connected bank show up in Autofatture. The name the bank sends is kept.

## Sync now [#sync-now]

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-connections/$ID/sync \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Getbeel already syncs every 6 hours. Banks allow about four reads a day without the user present, and this call uses one: once they are used up it answers `429 bank_daily_limit`. Other errors: `409 sync_in_progress`, `409 bank_connection_inactive`, `409 bank_connection_requires_reconnect`.

## Disconnect [#disconnect]

```bash
curl -X DELETE https://www.getbeel.com/api/v1/bank-connections/$ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Closes the consent at the bank and deletes the key. Statements, transactions and matches stay.

## MCP [#mcp]

AI assistants get `list_bank_connections`, `sync_bank_connection` and `reconnect_bank_connection` (returns the link the user opens to log in to the bank). Connecting a new bank needs the private key, which never goes through an assistant: do it in the app or with the API.
