Get a connection

curl --request GET \
  --url https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "con_FINICITY_41294",
  "client_id": "cli_01HXYZ8A6N7K2W9PQ4T5Z3V6E0",
  "source": "FINICITY",
  "status": "initiated",
  "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": {
      "promise": "always"
    },
    "balance": {
      "promise": "always"
    },
    "available_balance": {
      "promise": "always"
    },
    "statements": {
      "promise": "always"
    },
    "check_images": {
      "promise": "always"
    }
  },
  "realized_capabilities": {
    "transactions": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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"
}

{
  "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"
      }
    ]
  }
}

{
  "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"
      }
    ]
  }
}

{
  "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"
      }
    ]
  }
}

GET

connections

{connection_id}

Get a connection

curl --request GET \
  --url https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "id": "con_FINICITY_41294",
  "client_id": "cli_01HXYZ8A6N7K2W9PQ4T5Z3V6E0",
  "source": "FINICITY",
  "status": "initiated",
  "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": {
      "promise": "always"
    },
    "balance": {
      "promise": "always"
    },
    "available_balance": {
      "promise": "always"
    },
    "statements": {
      "promise": "always"
    },
    "check_images": {
      "promise": "always"
    }
  },
  "realized_capabilities": {
    "transactions": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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": {
      "status": "succeeded",
      "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"
}

{
  "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"
      }
    ]
  }
}

{
  "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"
      }
    ]
  }
}

{
  "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"
      }
    ]
  }
}

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.

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 an account. Aggregator sources (FINICITY, MX) and FDE back a Connection; PDF does not.

Values:

FINICITY — Finicity aggregation
MX — MX aggregation
FDE — Financial Document Extraction (LedgerSync proprietary)
PDF — Uploaded bank statements. Read-only: exposed on /accounts and /transactions (statements are not served for PDF), and never as a Connection (PDF accounts have connection_id: null).

Available options:

FINICITY,

MX,

FDE,

PDF

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

Show child attributes

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).

Show child attributes

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).

Show child attributes

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.

Show child attributes

_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.

Show child attributes

updated_at

string<date-time>

Health

Clients

Connections

Settings

Institutions

Accounts

Transactions

Statements

Checks

Operations

Webhooks

ApiKeys

Sandbox

Metrics

PortalGating

Get a connection

Authorizations

Path Parameters

Query Parameters

Response