Skip to main content
GET
/
connections
/
{connection_id}
Get a connection
curl --request GET \
  --url https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "con_FINICITY_41294",
  "client_id": "cli_01HXYZ8A6N7K2W9PQ4T5Z3V6E0",
  "created_at": "2023-11-07T05:31:56Z",
  "institution": {
    "id": "<string>",
    "name": "Chase",
    "logo_url": "<string>"
  },
  "last_refreshed_at": "2023-11-07T05:31:56Z",
  "last_error": {
    "code": "unknown_api_key",
    "message": "The API key you presented doesn't match any active key.",
    "type": "auth_error",
    "doc_url": "https://portal.ledgersyncappv2.com/errors/unknown_api_key",
    "category": "AUTH_ERROR",
    "is_user_actionable": true,
    "source_diagnostic_code": "FIN-103",
    "param": "client.email",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "errors": [
      {
        "param": "client.email",
        "message": "must be a valid email address",
        "code": "invalid_email"
      }
    ]
  },
  "expected_capabilities": {
    "transactions": {},
    "balance": {},
    "available_balance": {},
    "statements": {},
    "check_images": {}
  },
  "realized_capabilities": {
    "transactions": {
      "last_success_at": "2023-11-07T05:31:56Z",
      "next_refresh_after": "2023-11-07T05:31:56Z",
      "last_error": {
        "code": "unknown_api_key",
        "message": "The API key you presented doesn't match any active key.",
        "type": "auth_error",
        "doc_url": "https://portal.ledgersyncappv2.com/errors/unknown_api_key",
        "category": "AUTH_ERROR",
        "is_user_actionable": true,
        "source_diagnostic_code": "FIN-103",
        "param": "client.email",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "errors": [
          {
            "param": "client.email",
            "message": "must be a valid email address",
            "code": "invalid_email"
          }
        ]
      }
    },
    "balance": {
      "last_success_at": "2023-11-07T05:31:56Z",
      "next_refresh_after": "2023-11-07T05:31:56Z",
      "last_error": {
        "code": "unknown_api_key",
        "message": "The API key you presented doesn't match any active key.",
        "type": "auth_error",
        "doc_url": "https://portal.ledgersyncappv2.com/errors/unknown_api_key",
        "category": "AUTH_ERROR",
        "is_user_actionable": true,
        "source_diagnostic_code": "FIN-103",
        "param": "client.email",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "errors": [
          {
            "param": "client.email",
            "message": "must be a valid email address",
            "code": "invalid_email"
          }
        ]
      }
    },
    "available_balance": {
      "last_success_at": "2023-11-07T05:31:56Z",
      "next_refresh_after": "2023-11-07T05:31:56Z",
      "last_error": {
        "code": "unknown_api_key",
        "message": "The API key you presented doesn't match any active key.",
        "type": "auth_error",
        "doc_url": "https://portal.ledgersyncappv2.com/errors/unknown_api_key",
        "category": "AUTH_ERROR",
        "is_user_actionable": true,
        "source_diagnostic_code": "FIN-103",
        "param": "client.email",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "errors": [
          {
            "param": "client.email",
            "message": "must be a valid email address",
            "code": "invalid_email"
          }
        ]
      }
    },
    "statements": {
      "last_success_at": "2023-11-07T05:31:56Z",
      "next_refresh_after": "2023-11-07T05:31:56Z",
      "last_error": {
        "code": "unknown_api_key",
        "message": "The API key you presented doesn't match any active key.",
        "type": "auth_error",
        "doc_url": "https://portal.ledgersyncappv2.com/errors/unknown_api_key",
        "category": "AUTH_ERROR",
        "is_user_actionable": true,
        "source_diagnostic_code": "FIN-103",
        "param": "client.email",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "errors": [
          {
            "param": "client.email",
            "message": "must be a valid email address",
            "code": "invalid_email"
          }
        ]
      }
    },
    "check_images": {
      "last_success_at": "2023-11-07T05:31:56Z",
      "next_refresh_after": "2023-11-07T05:31:56Z",
      "last_error": {
        "code": "unknown_api_key",
        "message": "The API key you presented doesn't match any active key.",
        "type": "auth_error",
        "doc_url": "https://portal.ledgersyncappv2.com/errors/unknown_api_key",
        "category": "AUTH_ERROR",
        "is_user_actionable": true,
        "source_diagnostic_code": "FIN-103",
        "param": "client.email",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "errors": [
          {
            "param": "client.email",
            "message": "must be a valid email address",
            "code": "invalid_email"
          }
        ]
      }
    }
  },
  "_debug": {
    "source_used": "<string>"
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

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.

Path Parameters

​
connection_id
string
required

Canonical Connection id of the form con_<SOURCE>_<bankAccountId> (e.g. con_FINICITY_41294, con_MX_1224, con_FDE_5009). Only the canonical shape is accepted here. The placeholder UUID id returned by POST /v3/clients/{id}/connections (con_<uuid>, e.g. con_01HXYZ8A6N7K2W9PQ4T5Z3V6E0) is not a valid value — calls with it return 400 with missing source separator. See the lifecycle prose at the top of this document for the full id-format contract.

Example:

"con_FINICITY_41294"

Query Parameters

​
client_id
string
required

The Client (cli_…) to scope the read to. Required on account, transaction, and statement reads — LedgerSync's backend data APIs are scoped per end-user, so these resources are resolved within a single Client.

Response

The Connection.

​
id
string
required

Connection identifier. Two shapes can appear depending on lifecycle state:

  • con_<uuid> — placeholder id surfaced during the connection_with_action result while the connection is pending. Used only to route the widget step. Calling GET /v3/connections/{placeholder_uuid} returns 400 with missing source separator.
  • con_<SOURCE>_<bankAccountId> — canonical id once the connection reaches active. Every other endpoint (/accounts, /transactions, /statements, refresh, delete) expects this form.

See the lifecycle prose at the top of this document.

Example:

"con_FINICITY_41294"

​
client_id
string
required
Example:

"cli_01HXYZ8A6N7K2W9PQ4T5Z3V6E0"

​
source
enum<string>
required

Financial-data source backing a connection. All sources wrap upstream aggregators or extraction pipelines.

Values:

  • FINICITY — Finicity aggregation
  • MX — MX aggregation
  • FDE — Financial Document Extraction (LedgerSync proprietary)
Available options:
FINICITY,
MX,
FDE
​
status
enum<string>
required

Connection lifecycle status.

  • initiated — Connection started, waiting for end-user or upstream to complete
  • requires_action — Awaiting MFA or reauthorization from the end-user
  • active — Healthy, refreshing on schedule
  • failed — Connection failed; review last_error
  • disconnected — End-user revoked or LedgerSync disconnected
Available options:
initiated,
requires_action,
active,
failed,
disconnected
​
created_at
string<date-time>
required
​
institution
object | null
​
last_refreshed_at
string<date-time> | null
​
last_error
object | null

The inner error payload. Used as the top-level body of an HTTP error response (wrapped in ErrorEnvelope) and as the embedded error field on resources that record a failure (like Operation.error).

​
expected_capabilities
object | null

Catalog-derived promise for each capability we may deliver on this connection. Plaid-style 4-tier: always/usually/sometimes/never. Set when the connection enters active and refreshed when the underlying catalog row changes. Phase 1 emits only always/never (per-FI tiering uses a profile catalog scheduled for Phase 2).

​
realized_capabilities
object | null

Observed outcome of the most recent attempt at each capability. Rolled-up across the connection's accounts — worst-status-wins per capability. See RealizedCapabilities for the per-capability shape.

​
_debug
object

Observable-only debug metadata. Do not parse, do not branch routing on these values. Fields under _debug may be removed, renamed, or hashed at any time. Use the documented realized_capabilities and last_error blocks for capability and failure data.

​
updated_at
string<date-time>