GetbeelDocs

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 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

  1. Create an account at Enable Banking.

  2. In the control panel 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:

    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.

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.

Connect a bank

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:

{
  "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

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. Each account has its IBAN, balance, number of synced transactions and pending_transactions (see below).

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.

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

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

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

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

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.

On this page