> ## Documentation Index > Fetch the complete documentation index at: https://docs.ledgersyncappv2.com/llms.txt > Use this file to discover all available pages before exploring further. # LedgerSync-hosted pick-and-connect page (browser-facing) > Browser-facing HTML page — **not** an integrator API call. A member lands here when they open the `url` returned by `POST /clients/{client_id}/connect-session`. They search for their own bank, pick it, and are handed off to the per-source connect widget (Finicity Connect / the MX wrapper page / the FDE connect page) to enter credentials. LedgerSync never collects bank credentials on this page. No API key is required: the opaque session token in the query string is the capability. Tampered, expired, or revoked tokens render a static error page (`text/html`, not the JSON error envelope). The page drives its own same-origin search/connect/poll calls under `/connect-session/*` — those are internal browser plumbing, not part of the integrator API. ## OpenAPI ````yaml /openapi.yaml get /connect-session openapi: 3.1.0 info: title: LedgerSync API version: '2026-05-22' summary: A modern REST API for connecting bank accounts and pulling financial data description: > > **First time here?** The [**Getting started** guide](https://portal.ledgersyncappv2.com/dashboard/getting-started) walks the full integration end-to-end (about 15 minutes). This page is the endpoint reference for after you've read it. Welcome. This is LedgerSync's API for connecting your users' bank accounts and pulling their transactions, statements, and account details. Everything is JSON over HTTPS. Errors are easy to read. Webhooks fire as state changes. Sandbox is one key away. ## Connection lifecycle and the two `connection.id` formats A Connection's `id` changes shape once the user finishes linking their bank — there are two distinct identifiers, and you must only use the canonical one to read accounts, transactions, or statements. 1. **Placeholder id (pending state).** `POST /v3/clients/{id}/connections` returns `202 Accepted`. The initiate operation first surfaces a `connection_with_action` result whose embedded `connection.id` is a UUID-prefixed placeholder of the form `con_` (e.g. `con_01HXYZ8A6N7K2W9PQ4T5Z3V6E0`), paired with a `widget_url`. The placeholder is **not** a valid id for any other endpoint — calling `GET /v3/connections/{placeholder_uuid}` returns `400 Bad Request` with `missing source separator`. Treat it as opaque routing state for the widget step only. 2. **Canonical id (active state).** Once the user finishes the widget and the source pushes its first callback, the connection moves to `status=active` and the `connection.active` webhook fires. From that point on every surface — `GET /v3/clients/{id}/connections`, `GET /v3/connections/{id}`, the webhook payload, and the `connection.initiate` operation when re-polled — reports the canonical id `con__` (for example `con_FINICITY_41294`, `con_MX_1224`). **This** is the id every other endpoint accepts (`/accounts`, `/transactions`, `/statements`, refresh, delete). The correct integration pattern is therefore: - Initiate the connection, capture `operation_id`. - Poll `GET /v3/operations/{operation_id}` (or wait for the `connection.active` webhook) until `status=succeeded`. - Read `result.connection.id` **from the succeeded operation** — that is the canonical id. Store it; do not store the placeholder. Do not try to `GET /v3/connections/{placeholder_uuid}` during the pending window. Listing endpoints (`GET /v3/clients/{id}/connections`, `GET /v3/connections/{id}`) only ever return canonical ids, because they only surface connections that have reached `active`. ## Quick start Mint a sandbox key in the developer portal, then create your first **Client** (your end-user — the person whose bank we'll be reading): ```bash curl \ https://api-sandbox.ledgersyncappv2.com/v3/clients \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"email":"alice@example.com","name":"Alice"}' ``` You'll get back a `Client` object with an `id`. From there the full flow is: 1. **Register a webhook** at `POST /v3/webhooks/subscriptions` so you can be notified when the connection progresses. 2. **Initiate a connection** at `POST /v3/clients/{id}/connections` with an `institution_id` from `GET /v3/institutions`. LedgerSync's router picks the underlying source. Every source hands back a `widget_url` in the `connection.requires_action` result — for FDE it points at a LedgerSync-hosted connect page where credentials are entered, never sent to the API. 3. **Open the widget URL** in your user's browser. They pick their bank, log in, and choose accounts to share. 4. **Receive `connection.active`** on your webhook URL. List accounts and transactions. **Don't want to build your own bank picker?** Skip steps 2–3: call `POST /v3/clients/{id}/connect-session` to get a LedgerSync-hosted link, and email it to your member. They open it, search for their own bank, pick it, and connect it — all on a page we host, with no `institution_id` needed up front. You still receive `connection.active` on your webhook exactly as above. Revoke a link at any time with `DELETE /v3/clients/{id}/connect-session/{sid}`. (This is the v3 replacement for the old `account/add/lite` widget.) Want a step-by-step walkthrough with curl per step plus a sandbox shortcut that skips the widget? Read the [Getting started guide](https://portal.ledgersyncappv2.com/dashboard/getting-started). ## Authentication Pass your secret key in the `Authorization` header as a Bearer token: `Authorization: Bearer sk_test_...` (sandbox) or `Bearer sk_live_...` (production). Treat secret keys like passwords — never embed them in mobile apps or front-end code. ## Conventions **Sync vs async.** Most endpoints respond synchronously — you get the resource back right away. A handful of flows are genuinely async (initiating a bank connection, extracting a statement, generating a verification report); those return `202 Accepted` with an `operation_id` you can poll, and the matching webhook fires when the work finishes. **Errors.** Every error is `{ "error": { "code", "message", "doc_url", "type" } }`. Branch on `code`. Click `doc_url` for the troubleshooting page. Every response carries an `X-LS-Trace-Id` header — paste it in support tickets and we can jump straight to your request. **Webhooks.** Every delivery carries `X-LS-Webhook-Signature`, computed over the **raw request body** with HMAC-SHA256. Verify it before trusting the payload. Full event catalog + signature example on the [Webhooks tab](#webhooks). ## Need help? Email [support@ledgersync.com](mailto:support@ledgersync.com) or open a thread in the developer portal. Quote the `X-LS-Trace-Id` from your response — it makes everything faster. contact: name: LedgerSync Developer Support email: support@ledgersync.com url: https://portal.ledgersyncappv2.com license: name: Proprietary url: https://ledgersync.com/terms servers: - url: https://api-sandbox.ledgersyncappv2.com/v3 description: >- Sandbox — use `sk_test_...` keys from the developer portal. Routes to the real Finicity and MX sandbox banks (FinBank, mxbank) via the same connector code paths as production. - url: https://api.ledgersyncappv2.com/v3 description: >- Production — use `sk_live_...` keys. Hits real banks via Finicity, MX, or FDE depending on the connection. security: - bearer: [] tags: - name: Clients description: | A **Client** is the end-user whose bank accounts you're managing — usually a real person or business. You create one Client per user before linking any accounts. Pass your own `external_id` to join Clients back to records in your system. - name: Connections description: | A **Connection** links a Client to a bank or financial-data source (Finicity, MX, or FDE). One Client can have many Connections — one per bank they've linked. You initiate a Connection, the user finishes it (widget or MFA), and a `connection.active` webhook tells you when it's ready. - name: Accounts description: | Once a Connection goes active, the bank's accounts (checking, savings, credit, loans) show up here. Use these endpoints to list, inspect, and refresh them. - name: Transactions description: | Posted transactions and pending charges for an account. New transactions are surfaced by a future push-delivery event for transactions after each refresh; you can also list/page them directly. - name: Statements description: | Period statements (usually monthly PDFs) the bank publishes. For FDE-sourced statements, extracted line items are attached after OCR completes. - name: Operations description: | The handful of LedgerSync calls that genuinely run asynchronously return an `operation_id`. Poll it here, or just listen for the matching webhook — your call. - name: Webhooks description: | Manage where LedgerSync delivers event notifications. Each subscription has its own HMAC signing secret. Rotate it whenever you want — the old secret stays valid for 24 hours so deploys don't break verification. - name: ApiKeys description: | Create, list, and revoke API keys. Keys are scoped to one environment (sandbox or live). The plaintext secret is returned exactly once at creation — store it somewhere safe. - name: Institutions description: | The unified v3 institution catalog. Search by name; pick a row; pass its `id` to `POST /clients/{client_id}/connections`. LedgerSync's router decides which underlying source (Finicity, MX) to use — integrators don't pick a source. - name: Settings description: | Account-level settings the integrator manages once per environment. Currently exposes the redirect-URL allowlist consulted at `/connections/initiate`. Same scope as Stripe Connect / Plaid Link / OAuth — register your app's redirect URIs once, not per end-user. - name: Sandbox description: | Sandbox-only helpers. Use `GET /sandbox/institutions` to list the sandbox-eligible test banks you can target when creating a sandbox connection (Finicity FinBank, MX `mxbank`, FDE test extractors). Lifecycle transitions and webhooks come from the same real connector paths as live traffic — no synthetic lifecycle driver, no replay fixtures. Drive the widget with the public test bank credentials documented in the developer portal. - name: Metrics description: | Read-only aggregations powering the developer portal's "Metrics" page. Every endpoint is scoped to the authenticated principal's customer and environment — `sandbox` and `live` data never mix across the wire. Default window when `from`/`to` are omitted is the last 30 days (max 366). - name: Health description: A simple liveness probe. No auth required. - name: PortalGating description: | Developer-portal access-request endpoints (sandbox + live gating). These are HMAC-signed calls from the LedgerSync portal to v3 and not part of the integrator-facing API surface. Documented here so the single spec stays authoritative. paths: /connect-session: get: tags: - Connections summary: LedgerSync-hosted pick-and-connect page (browser-facing) description: | Browser-facing HTML page — **not** an integrator API call. A member lands here when they open the `url` returned by `POST /clients/{client_id}/connect-session`. They search for their own bank, pick it, and are handed off to the per-source connect widget (Finicity Connect / the MX wrapper page / the FDE connect page) to enter credentials. LedgerSync never collects bank credentials on this page. No API key is required: the opaque session token in the query string is the capability. Tampered, expired, or revoked tokens render a static error page (`text/html`, not the JSON error envelope). The page drives its own same-origin search/connect/poll calls under `/connect-session/*` — those are internal browser plumbing, not part of the integrator API. operationId: getConnectSessionPage parameters: - in: query name: token required: true description: The opaque connect-session token from the emailed link. schema: type: string responses: '200': description: The pick-and-connect page. content: text/html: schema: type: string '400': description: | Token was missing, malformed, signature-invalid, expired, or revoked. A static error page is rendered (`text/html`). content: text/html: schema: type: string security: [] components: securitySchemes: bearer: type: http scheme: bearer bearerFormat: LedgerSync API key description: | Pass your secret key in the `Authorization` header as a Bearer token: `Authorization: Bearer sk_test_...` (sandbox) or `Bearer sk_live_...` (production). Keys are created in the developer portal and the plaintext secret is shown exactly once at creation. Treat them like passwords — never embed them in mobile apps or front-end code. ````