Step 1: Create a Connect Token

The first step in linking a customer’s bank account is creating a connect token. A connect token is a short-lived JWT that authorizes the Meld Connect Widget to start a connection session for a specific customer with a specific set of products and regions. This page walks developers through generating a token, configuring it correctly, and using the response to launch the widget in Step 2.

Before you begin

You have a Meld sandbox or production API key
You have decided which products you need (you can also use optional products)
You know the regions your customers bank in, or are comfortable leaving regions unset
Your server is calling the endpoint — never call this endpoint from the browser or mobile client, the API key is a secret

Create the token

Send a POST request to {api_base_url}/bank-linking/connect/start using your API key. The response contains the connectToken you will use in Step 2: Launch the widget.

For the full request and response schema, refer to the Bank Linking — Create Connect Token API reference.

The connect token is used only while the user is making the connection to their bank and expires after 3 hours. You do not have to persist it — once the connection completes it cannot be reused. To track a connection over time, use the customerId returned in the response, or the externalCustomerId you optionally pass in.

Be deliberate about the regions and products you request. In Step 3, when the user selects their institution, only institutions that support all requested products and are in one of the requested regions appear in the widget. Choosing too many products or too few regions can dramatically shrink the institution list. If you don’t know the region in which your customer banks, omit the regions parameter entirely.

Disabling / re-enabling service providersIf you disable a service provider in the Meld dashboard and later re-enable it (with the same or different credentials), use new customerId / externalCustomerId values for subsequent connections. Reusing prior identifiers can result in an Error creating user when the customer selects an institution.

Skipping or prepopulating the Meld picker

If you already know which institution the user wants to link (for example, you collect that in your own UI), you have two options to make the flow more seamless:

Prepopulate the search box. Pass the institution name as a string when creating the connect token. The Meld picker autofills the search input so matching institutions appear by default. The user can still edit the search string.
Skip the picker entirely. Pass the institutionId corresponding to the user’s bank. This skips the Meld picker screen and sends the user straight to the institution login.

To resolve an institution name to a Meld institutionId, use the /institutions endpoint. Note that for MX, not all institutions that support transactions also support historical transactions, so HISTORICAL_TRANSACTIONS appears as a separate product in the institution search response. However, when listing products in /connect/start, pass TRANSACTIONS only — HISTORICAL_TRANSACTIONS is not a valid value for the products array on /connect/start. A key part of building the request body is the list of products. For more information on the available products and which to request, see Supported Bank Linking Products.

Sample request

curl --location 'https://api-sb.meld.io/bank-linking/connect/start' \
--header 'Meld-Version: 2022-11-10' \
--header 'Content-Type: application/json' \
--header 'Authorization: BASIC ***Redacted API Key***' \
--data '{
  "externalCustomerId": "testCustomer",
  "products": [
    "BALANCES",
    "OWNERS",
    "IDENTIFIERS",
    "TRANSACTIONS",
    "INVESTMENT_HOLDINGS",
    "INVESTMENT_TRANSACTIONS"
  ],
  "regions": ["US", "CA"],
  "institutionSearchString": "Fidelity"
}'

Sample response

{
    "id": "WQ46XEVzT14vrrDq6LSJVg",
    "connectToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZWRpcmVjdCI6dHJ1ZSwicmVnaW9ucyI6WyJVUyIsIkNBIl0sImlzcyI6Im1lbGQuaW8iLCJjb25uZWN0aW9uIjoiV1E0NlhFVnpUMTR2cnJEcTZMU0pFZCIsImV4cCI6MTY4Njc5ODkzMywiaWF0IjoxNjg2Nzg0NTMzLCJhY2NvdW50IjoiVzlrYmtSbWU5VlQyaXo2cUFTZkFmMiIsImN1c3RvbWVyIjoiV1E0NlhEcllZTVlyZTlSQmt3YXl5USIsInByb2R1Y3RzIjpbIlRSQU5TQUNUSU9OUyIsIkJBTEFOQ0VTIiwiSURFTlRJRklFUlMiLCJPV05FUlMiXSwicm91dGluZ1Byb2ZpbGUiOiJXR3ZGWHRYYkRvQ2VXc3hVdHVpeFB5In0.jAwpUokwkSKi7BTwKJOY_Y6XAPv_O8yOi6mVaUKxnMI",
    "customerId": "WQ46XDrYYMYre9RBkwayyZ",
    "externalCustomerId": "testCustomer",
    "widgetUrl": "https://institution-connect-sb.meld.io?connectToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZWRpcmVjdCI6dHJ1ZSwicmVnaW9ucyI6WyJVUyIsIkNBIl0sImlzcyI6Im1lbGQuaW8iLCJjb25uZWN0aW9uIjoiV1E0NlhFVnpUMTR2cnJEcTZMU0pFZCIsImV4cCI6MTY4Njc5ODkzMywiaWF0IjoxNjg2Nzg0NTMzLCJhY2NvdW50IjoiVzlrYmtSbWU5VlQyaXo2cUFTZkFmMiIsImN1c3RvbWVyIjoiV1E0NlhEcllZTVlyZTlSQmt3YXl5USIsInByb2R1Y3RzIjpbIlRSQU5TQUNUSU9OUyIsIkJBTEFOQ0VTIiwiSURFTlRJRklFUlMiLCJPV05FUlMiXSwicm91dGluZ1Byb2ZpbGUiOiJXR3ZGWHRYYkRvQ2VXc3hVdHVpeFB5In0.jAwpUokwkSKi7BTwKJOY_Y6XAPv_O8yOi6mVaUKxnMI"
}

Key response fields

Field	Description
`id`	The Meld connection id. Use this to look up the connection later.
`connectToken`	The JWT used to launch the widget. Expires after 3 hours.
`customerId`	Meld’s id for the customer. Persist this to track the customer across connections.
`externalCustomerId`	The id you passed in (if any), echoed back.
`widgetUrl`	The full URL with the token attached. You can load this directly in an iframe to launch the widget.

Common errors

HTTP status	Likely cause	Developer action
`401 Unauthorized`	Missing or invalid `Authorization` header	Verify the API key value and the `BASIC` prefix; confirm you are hitting the correct environment
`400 Bad Request`	Invalid product name, both required and optional product overlap, or unsupported region	Check `products` / `optionalProducts` / `regions` values against the API reference
`400 Bad Request`	No required product specified when using `optionalProducts`	Move at least one product into the `products` array
`404 Not Found`	The `institutionId` you passed does not exist	Re-resolve the institution via the `/institutions` endpoint
`5xx`	Transient Meld or provider issue	Retry with backoff; if it persists, contact Meld support

Now that you have your connect token, you are ready to move on to launching the widget.

Welcome

AI Toolkit

Meld API

Stablecoins & Digital Assets

Bank Linking

Step 1: Create a Connect Token

Before you begin

Create the token

Skipping or prepopulating the Meld picker

Sample request

Sample response

Key response fields

Common errors

​Before you begin

​Create the token

​Skipping or prepopulating the Meld picker

​Sample request

​Sample response

​Key response fields

​Common errors

Before you begin

Create the token

Skipping or prepopulating the Meld picker

Sample request

Sample response

Key response fields

Common errors