Create bank link

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 is refused when the account has locked bank enrollment (enrollmentPolicy.bankEnrollmentLocked is true on the subaccount) and the subaccount's enrollmentPolicy.bankEnrollment value does not allow a bank link for this card. Otherwise the check does not refuse. 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.
  • 403 PLAID_CUSTOMIZATION_NOT_PROVISIONED: Plaid refused the Link customization this link asked for, because the account's Plaid client cannot use it, and no fallback applied. Nothing is created. The message is This account is not fully set up for Plaid bank linking yet. A customization other than amex_only (one set by the bank-linking policy's plaidLinkCustomizationName) answers this at once. When Plaid refuses amex_only, from filters.linkCustomizationName or from the policy, the create is retried once with the environment's pinned customization in its place, or with no customization when the environment pins none. If Plaid accepts the retry, the link is created as usual: its hosted session opens without the amex_only customization, and its completion is still held to American Express institutions. For amex_only, only a refused retry answers this error. Astrada fixes it in the account's Plaid setup, so sending the same request again does not help.
  • 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
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Bank link creation request

Headers
Responses

Language
Credentials
OAuth2
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json