Skip to main content
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:
  1. 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.
  2. 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

FieldDescription
idThe Meld connection id. Use this to look up the connection later.
connectTokenThe JWT used to launch the widget. Expires after 3 hours.
customerIdMeld’s id for the customer. Persist this to track the customer across connections.
externalCustomerIdThe id you passed in (if any), echoed back.
widgetUrlThe full URL with the token attached. You can load this directly in an iframe to launch the widget.

​
Common errors

HTTP statusLikely causeDeveloper action
401 UnauthorizedMissing or invalid Authorization headerVerify the API key value and the BASIC prefix; confirm you are hitting the correct environment
400 Bad RequestInvalid product name, both required and optional product overlap, or unsupported regionCheck products / optionalProducts / regions values against the API reference
400 Bad RequestNo required product specified when using optionalProductsMove at least one product into the products array
404 Not FoundThe institutionId you passed does not existRe-resolve the institution via the /institutions endpoint
5xxTransient Meld or provider issueRetry 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.