> ## 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 Connections: Ongoing Access, Consent and Renewal

> A connection is a person's permission to read one bank. See its statuses, how consent ends, how to renew it, and how to stop access or delete the data.

A Didit bank connection is a person's or company's permission for your application to read one bank, with its consent dates, its sync state and its accounts.
A completed [Bank Link](https://docs.didit.me/core-technology/bank-verification/bank-link.md) creates it, and it lives for the time the bank and the person allow.

Bank data is available for sandbox applications; a live application's calls answer `404` until live access is announced.

## One-time and ongoing access

| | One-time | Ongoing |
| - | - | - |
| `access` | `one_time` (default) | `ongoing` |
| What happens | The data is read once when the person connects, then access ends (`status_reason: collection_complete`). | Access stays open until the consent ends or someone stops it. |
| Data afterwards | Readable through the same endpoints. | Synced automatically between one and four times a day depending on the bank, plus live syncs on demand. |
| Billing | Per check, see [pricing](https://docs.didit.me/getting-started/bank-verification-pricing.md) | Per active connection per month, see [pricing](https://docs.didit.me/getting-started/bank-verification-pricing.md) |

Ongoing access works at a bank only where that bank allows it.
Ask the [institutions endpoint](https://docs.didit.me/standalone-apis/bank-institutions-list.md) or read the [coverage page](https://docs.didit.me/core-technology/bank-verification/coverage.md).
Where a bank cannot keep access open, the person is told that the bank does not allow ongoing access and has to choose another bank.
Set `allow_one_time_fallback: true` to let the person continue with a one-time read after confirming the reduced access on their own screen: the connection is then `one_time`.

## Statuses

| `status` | Meaning | Data readable | Syncs | Billed |
| - | - | - | - | - |
| `pending` | The link completed and the first sync is running. | Not yet | Running | No |
| `active` | The consent is valid and syncing is healthy or retrying. | Yes | Yes | Yes |
| `renewal_required` | The consent ended, or the bank asks the person to sign in again. `status_reason` says which. | As last synced | No | No |
| `paused` | The balance cannot cover the month. | As last synced | No | No |
| `revoked` | Access was stopped by the person, the bank or you. `consent.ended_by` says who. | Until `consent.retain_until` | No | No |
| `deleted` | The connection and its data were deleted. | No | No | No |
| `failed` | The first sync never succeeded. | No | No | No |

`status_reason` is one of `collection_complete`, `consent_expired`, `consent_lapsed`, `bank_requires_sign_in`, `revoked_by_end_user`, `revoked_by_bank`, `revoked_by_customer`, `insufficient_balance`, `paused_by_customer` (reserved, no endpoint sets it today) and `first_sync_failed`.

## Consent

The bank sets the end of the consent, up to the `consent_days` you asked for.
Every connection shows its real dates in `consent`:

* `expires_at` and `renew_by`: the consent's end. Renew before it for no gap.
* `renewable_until`: the last moment the same connection can be revived after the consent ended.
* `renewed_count`, `version`, `scopes_granted` and `accounts_granted`: what was granted, and how many times it was renewed.

Consent lasts as long as the bank allows.
Read the actual value on each connection and the per-bank value on the institution.

## Renewal

A renewal keeps the connection id and every account id, and history continues without duplicates.

1. Didit sends `bank.connection.consent_expiring` 14, 7 and 1 day before the end.
2. Call [`POST /v3/bank/connections/{id}/renew/`](https://docs.didit.me/standalone-apis/bank-connection-renew). It answers `409 renewal_not_needed` while more than 30 days are left and `409 renewal_window_expired` after `consent.renewable_until`. Otherwise it answers `201` with a renew link.

The page where the person completes a renewal is not available yet, so do not send people to a renew link today.

If the person lets the consent lapse, the connection becomes `renewal_required`: data stays readable as last synced and nothing is charged.
After `consent.renewable_until` it is `revoked` with `status_reason: consent_lapsed` and the person connects again.

For the full flow see [Renew a bank consent](https://docs.didit.me/use-cases/renew-bank-consent.md).

## Stop access

| Who | How | What happens |
| - | - | - |
| The person | **Stop sharing** at their bank | `bank.connection.revoked` with `ended_by: end_user` or `bank` |
| You | [`revoke_connection`](https://docs.didit.me/standalone-apis/bank-connection-revoke) | Bank fetches stop at once. The consent reads `revocation_pending`, then `revoked` when the bank confirms. The data already read stays readable until you delete the connection or `consent.retain_until` passes. |
| You | [`delete_connection`](https://docs.didit.me/standalone-apis/bank-connection-delete) | Stops access and deletes the connection and its accounts, balances and transactions. Irreversible. |

Stopping access is not deleting.
Read [Data, consent and deletion](https://docs.didit.me/core-technology/bank-verification/data-consent-and-deletion.md) for exactly what deletion removes.

## A deleted connection

A deleted connection answers only `id`, `status` (`deleted`), `status_reason`, `created_at` and `erasure`.
`status_reason` is `deleted_by_customer`, `consent_lapsed`, `retention_elapsed` or `application_deleted`.
Every other field is absent.

## Duplicates

A new link that resolves to exactly the accounts you already share with the same `end_user.reference` at the same bank completes as a renewal of that connection (`reused: true`) and charges nothing twice.
Any other overlap ends the link `failed` with `duplicate_conflict` and `conflicts_with`, before anything is stored or charged.
Renew the existing connection, or create the link again with `"duplicates": "allow"` for an independent second connection.

## Manage the connections of your clients

* List with filters: [`GET /v3/bank/connections/`](https://docs.didit.me/standalone-apis/bank-connections-list) takes `status`, `access`, `institution_id`, `country`, `vendor_data`, `end_user_reference`, `consent_expires_before` and `created_after`.
* See what a connection costs with its `billing` object: the unit, the price and the month already settled.


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