Start a new bank connection

Kick off a connection between a Client and a bank. Send only institution_id (a v3 catalog id from GET /v3/institutions). LedgerSync’s router picks the underlying source (Finicity vs MX) per its routing rules — integrators don’t pick a source.

The response:

• Finicity / MX — we hand back a widget URL. Open it in the user’s browser (or your mobile webview) and they’ll finish linking. For MX the URL points at a LedgerSync-hosted wrapper page (GET /connections/mx-wrapper) that embeds the MX widget and gives you the same redirect_url + ls_token completion hop as Finicity (verify it at POST /connections/redirect-token/verify).
• FDE — we return a widget_url to a LedgerSync-hosted connect page where the end user enters their bank credentials and answers any security questions in-session. Raw credentials are never sent to the API.

This one’s genuinely async — the bank or document pipeline takes a few seconds to a minute. You get 202 Accepted and an operation_id right away; the connection.active (or connection.requires_action / connection.failed) webhook fires when it’s done. Poll GET /operations/{operation_id} if you can’t run a webhook handler.

Note on connection.id. While this operation is queued/running, the embedded result.connection.id is a UUID-prefixed placeholder (con_<uuid>) and cannot be used with any other endpoint. The canonical id — con_<SOURCE>_<bankAccountId> such as con_FINICITY_41294 or con_MX_1224 — is only assigned once the user finishes the widget and the source pushes its first callback. Read the canonical id from GET /operations/{operation_id} once status=succeeded, or from the connection.active webhook. See the Connection lifecycle section at the top of this reference for the full handshake.