Skip to main content
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 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

Ongoing access works at a bank only where that bank allows it. Ask the institutions endpoint or read the coverage page. 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_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. 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/. 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.

Stop access

Stopping access is not deleting. Read Data, consent and deletion 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/ 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.
Last modified on November 22, 2026