Skip to main content
POST
curl
Didit’s Create a Bank Link endpoint starts one run of Bank Link on your server, to connect a bank or renew a connection, and returns the hosted url. Every field has a default, so the smallest request is {} plus what you want. Keep the returned id with your user and confirm the outcome yourself with Get a bank link or the bank.link.completed webhook. See the quickstart and Bank Link.

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

Body

application/json

Create a Bank Link. The smallest request is {} plus what you want: every field has a default.

mode
enum<string>
default:connect

connect (default) creates a new connection. renew needs connection_id and reuses that connection's settings.

Available options:
connect,
renew
connection_id
string<uuid>

The connection to renew. Only with mode: renew.

access
enum<string>
default:one_time

one_time (default) reads the data once. ongoing keeps access open until the consent ends or someone stops it. With institution_id set, a bank that cannot keep access open answers 400 ongoing_access_not_available before any screen. Without it, the bank picker lists only banks that can.

Available options:
one_time,
ongoing
country
string

Optional. Without it the person picks among the countries your application enabled. It has to be a country Bank Link serves; any other, ZZZ included, answers 400 invalid_request with field: country. An empty request body stays valid.

Pattern: ^[A-Z]{3}$
institution_id
string

Optional bank to preselect, from list_institutions. Skips the picker.

Maximum string length: 64
segment
enum<string>
default:any

Filters the picker and tells the bank which login to open where the bank separates them. Default any.

Available options:
personal,
business,
any
data
enum<string>[]

What to read. accounts is always included: name, type, currency, identifiers and the holder name where the bank shares it. Default ["accounts"].

Maximum array length: 3
Available options:
accounts,
balances,
transactions
history_days
integer
default:90

Days of transaction history to request, 1 to 365, default 90. The bank may deliver less: each account reports what it delivered in history_coverage. Cannot be sent with history_from.

Required range: 1 <= x <= 365
history_from
string<date>

Start date of the history to request, instead of history_days. Cannot be sent with history_days: both together answer 400 history_window_ambiguous. A date older than 365 days, or in the future, answers 400 window_not_available.

extended_history
enum<string>
default:standard

allow_extra_auth lets a bank that asks for one more confirmation release older history.

Available options:
standard,
allow_extra_auth

Ongoing only. How many days to ask the bank to keep access open, 1 or more. Default: the longest the bank allows. The connection reports the date the bank actually granted in consent.expires_at. With access: one_time it answers 400 invalid_request with field: consent_days.

Required range: 1 <= x <= 32767
ownership
object

Optional comparison of the account holder with a person or a company.

end_user
object

The person or company that connects the account.

redirect_url
string<uri>

Where the browser goes at the end, with link_id, status and a signed state (for display only: the webhook and get_link are authoritative). In a sandbox application a plain http address of localhost, 127.0.0.1 or [::1] (any port and path, no credentials, no fragment) needs no registration. Any other address answers 400 redirect_url_not_registered: registering other addresses is not available yet. Without a redirect_url the person finishes on Didit's own result page.

Maximum string length: 2048
allowed_origins
string<uri>[]

Accepted and not used today: reserved for Didit's embedded Bank Link, which is not released yet. HTTPS origins, up to 50.

Maximum array length: 50
language
string

Optional language code such as es or pt-BR. Otherwise the browser language.

Maximum string length: 16
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
vendor_data
string

Your own reference, returned on the link and the connection.

Maximum string length: 255
expires_in
integer
default:3600

Lifetime of the link in seconds, 300 to 86400. Default 3600.

Required range: 300 <= x <= 86400
duplicates
enum<string>
default:reuse

reuse (default) completes a link that resolves to accounts you already share as a renewal of that connection. allow creates an independent second connection.

Available options:
reuse,
allow
allow_one_time_fallback
boolean
default:false

With ongoing, lets the person continue with a one-time read at a bank that cannot keep access open, after confirming the reduced access on its own screen. The quote shows what that costs. Only with access: ongoing: with one-time access it answers 400 invalid_request with field: allow_one_time_fallback.

accept_reduced_grant
boolean
default:false

When the bank or the person grants less than you asked for, complete the link and charge only the granted scopes. Otherwise the link ends failed with reduced_grant and nothing is charged.

sandbox
object

Sandbox applications only: picks the Didit Test Bank customer. Ignored in a live application.

Response

The link was created.

One run of Bank Link for one person: connect a bank, or renew a connection. Confirm a link yourself with get_link: never trust an id sent by the browser.

id
string<uuid>
required

Identifier of the link.

mode
enum<string>
required
Available options:
connect,
renew
access
enum<string>
required
Available options:
one_time,
ongoing
status
enum<string>
required

State of the link. completed, cancelled, expired and failed are final.

Available options:
created,
opened,
connecting,
completed,
cancelled,
expired,
failed
url
string<uri> | null
required

The hosted page to send the person to. Returned only when the link is created; null on later reads, because the token is not stored.

client_token
string | null
required

The token for Didit's embedded Bank Link, which is not released yet: open url today. Returned only when the link is created; null on later reads. Single purpose and short lived. It carries no personal data. Never log it.

expires_at
string<date-time>
required

When an unredeemed link stops working.

connection_id
string<uuid> | null
required

The connection this link created or renewed, once status is completed.

check_id
string<uuid> | null
required

The ownership result of this link, when it asked for ownership.compare other than none.

reused
boolean
required

true when the link completed as a renewal of an existing connection because the person already shares exactly these accounts (duplicates: reuse). Nothing is charged twice.

error
object | null
required

Why the link failed, when status is failed. Otherwise null.

quote
object
required

The price of a link, pinned when it is created. The price charged is the quote's. Reads never bill.

vendor_data
string | null
required

Your reference from the request.

Last modified on November 22, 2026