Create bank link

post

https://api.astrada.co/bank-links

Creates a new bank link to initiate a bank enrollment. The response includes a hostedLink URL where the user can connect their bank account via Plaid.

The hosted link expires after 4 hours. If the link expires before the user completes enrollment, retrieve the bank link via GET /bank-links/{bankLinkId} to get a refreshed URL.

Creating a bank link with an ID that already exists for the account will return a 409 Conflict error, unless the existing link has expired.

A refused create returns a JSON body with statusCode and message. These errors also carry a code, a stable name to branch on so that you never match on message text (the 409 above has no code):

404 SUBACCOUNT_NOT_FOUND: subaccountId is not one of the account's subaccounts. Nothing is created. The message is Subaccount not found for this account.
403 BANK_ENROLLMENT_DISABLED: a create can be refused when the subaccount's enrollmentPolicy.bankEnrollment does not allow a bank link for this card and the account has locked it (enrollmentPolicy.bankEnrollmentLocked is true on the subaccount). Nothing is created. The message is Bank linking is not enabled for this card on this account. The body also has a reason: bank-enrollment-off when the setting is off, network-not-allowed when it does not allow the card's network, and network-unknown when it limits the networks and the request does not show the card's network. The card's network comes from the request: American Express when the link uses the amex_only customization, otherwise bin6 (a first digit of 4 is Visa, 2 or 5 is Mastercard, and any other digit, a 3 included, is unknown). Without bin6 it is unknown.
403 MASTERCARD_CLIENT_NOT_PROVISIONED and PLAID_EC_NOT_PROVISIONED: the account is not set up for bank linking on that provider yet. The messages are This account is not set up for Mastercard bank linking yet and This account is not set up for Plaid bank linking yet.
400 INVALID_LINK_FILTERS: filters asks for more than the account's bank-linking policy allows, or for a customization that is not allowed.
400 PROVIDER_NOT_ENABLED_FOR_ACCOUNT: provider is not enabled for the account.
400 PROVIDER_NOT_SUPPORTED_FOR_COUNTRY: no provider supports countryCode for the chosen provider.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Bank link creation request

string

required

length between 1 and 256

^[a-zA-Z0-9_-]+$

A client-provided identifier for the bank link. Must be alphanumeric with hyphens and underscores only.

subaccountId

uuid

required

The subaccount identifier to associate with this bank link. A subaccount that does not belong to the account is rejected with 404 (SUBACCOUNT_NOT_FOUND).

filters

object

Optional per-link narrowing of the account's bank-linking policy. Values may
only NARROW what the policy allows — the current system default is
accountTypes: [credit] (credit-card accounts only). Requests widening beyond
the policy are rejected with 400. Account-type enforcement is applied by the
provider at link-token creation and also filters the institution-select list.

bin6

string

^\d{6}$

First 6 digits captured client-side before an institution
pivot (e.g. an American Express BIN typed into the card form
before the SDK pivots to bank linking). Persisted with the
link. Attached as the completion-time bank-derived card's
first6digits when the completion has exactly one eligible
candidate account.

provider

string

enum

Open-banking provider to create the link on. Omitted, the
subaccount's configured default applies (system default:
plaid). A provider outside the subaccount's configured
allowlist, or one not enabled on the platform, is rejected
with 400. The provider is fixed at creation — every later
operation on the link uses the value it was created with.

Allowed:

countryCode

string

^[A-Z]{3}$

ISO 3166-1 alpha-3 country of the institution to connect
(e.g. USA, DEU). Omitted, the subaccount's configured
default applies (system default: USA). Combined with
provider to select the concrete integration; a country the
selected provider does not support is rejected with 400.

language

string

length ≤ 35

^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8}){0,3}$

Language of the hosted bank-linking screens, as a BCP 47 tag
such as en, en-US or sv-SE. A tag that matches the
pattern is accepted; any other value is rejected with 400.
For a Plaid link, the language part of the tag (sv for
sv-SE) is used when Plaid supports it, Astrada has turned
that language on, and no Link customization applies to the
link. Otherwise the screens are in English and the request
still succeeds. Plaid Link supports da, nl, en, et,
fr, de, hi, it, lv, lt, no, pl, pt, ro,
es, sv and vi. Plaid's Norwegian is no, so nb and
nb-NO fall back to English. Other providers ignore this
field. The language is kept with the link, so a refreshed
hosted link uses it again.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

201Bank link created

400The server cannot or will not process the request due to something that is perceived to be a client error

401Authentication credentials were either missing or incorrect

403Authentication credentials used do not have have permissions to perform the request

404The requested resource was not found on the server

409Request conflict with the current state of the target resource

500The server encountered an unexpected condition that prevented it from fulfilling the request