Refresh a connection

curl --request POST \
  --url https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "operation_id": "op_01HXYZ8A6N7K2W9PQ4T5Z3V6E0",
  "status": "queued",
  "poll_url": "https://api-sandbox.ledgersyncappv2.com/v3/operations/op_01HXYZ8A6N7K2W9PQ4T5Z3V6E0",
  "estimated_seconds": 123
}

Connections

Refresh a connection

Force a re-pull of accounts and recent transactions for this Connection. Banks usually post new transactions once a day so we already refresh active connections automatically — call this only when you have a specific reason to need fresher data (user just clicked a “refresh” button, you’re reconciling something time-sensitive).

Source-specific behavior

On-demand refresh is not uniformly available across sources. The HTTP outcome depends on the connection’s source:

Finicity (con_FINICITY_*) — returns 202 Accepted with an operation_id. The backend queues the refresh asynchronously; on success the account.refresh.completed webhook fires when the bank call finishes, and on terminal failure the account.refresh.failed webhook fires instead.
MX (con_MX_*) — returns 502 Bad Gateway with error.code = "refresh_not_supported" and error.category = "CAPABILITY_UNAVAILABLE". MX does not expose an on-demand refresh API — fresh data arrives only via aggregator-driven account.refresh.completed (and account.refresh.failed on terminal failure) webhooks. The v3 layer short-circuits before any operation row is created, so no zombie operation is left behind.
FDE (con_FDE_*) — returns 202 Accepted with an operation_id. FDE re-runs its document extraction pipeline; on success the account.refresh.completed webhook fires on completion, and on terminal failure the account.refresh.failed webhook fires instead.

Checking refresh capability ahead of time

Whether /refresh will succeed is enumerated on the connection’s realized_capabilities.transactions and realized_capabilities.balance blocks. If either has status = "unsupported", calling /refresh for that connection will return 502 with error.code = "refresh_not_supported". Branch on realized_capabilities instead of probing /refresh to discover capability gaps.

Empty-body POST

This endpoint takes no request body. Send an explicit Content-Length: 0 header — Google’s HTTPS load balancer in front of the API rejects body-less POSTs without one with 411 Length Required. Most HTTP clients add this automatically; some (raw fetch, certain SDKs in keep-alive mode) do not.

POST

connections

{connection_id}

refresh

Refresh a connection

curl --request POST \
  --url https://api-sandbox.ledgersyncappv2.com/v3/connections/{connection_id}/refresh \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

{
  "operation_id": "op_01HXYZ8A6N7K2W9PQ4T5Z3V6E0",
  "status": "queued",
  "poll_url": "https://api-sandbox.ledgersyncappv2.com/v3/operations/op_01HXYZ8A6N7K2W9PQ4T5Z3V6E0",
  "estimated_seconds": 123
}

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.

Headers

Idempotency-Key

string

Safe-retry key for POSTs. Send any unique string per logical request (a UUIDv4 is great). If the network drops and you retry with the same Idempotency-Key within 24 hours, you get the exact same response back instead of creating a duplicate.

Cached responses include failures (4xx and 5xx) too. If a call failed because of a bad input and you want to try again with the corrected input, use a fresh key — otherwise you'll keep getting the cached failure.

Maximum string length: 255

Example:

"6f1a8c50-3e9c-4d4a-b1f5-2c5b9a2f7d11"

Path Parameters

connection_id

string

required

Canonical Connection id (con_<SOURCE>_<bankAccountId>). The placeholder UUID returned during initiate is rejected here with 400 — only active connections can be refreshed.

Example:

"con_FINICITY_41294"

Body

application/json

No body. Send Content-Length: 0 so the upstream load balancer doesn't reject the request with 411.

The body is of type object | null.

Response

The request was accepted but the underlying work runs asynchronously. Use the returned operation_id to poll GET /operations/{operation_id} or just wait for the matching webhook event.

Returned with 202 Accepted for async operations.

operation_id

string

required

Example:

"op_01HXYZ8A6N7K2W9PQ4T5Z3V6E0"

status

enum<string>

required

Available options:

queued

poll_url

string<uri>

required

Example:

"https://api-sandbox.ledgersyncappv2.com/v3/operations/op_01HXYZ8A6N7K2W9PQ4T5Z3V6E0"

estimated_seconds

integer

Rough ETA for completion. Best-effort.

Disconnect and remove a connection Verify a redirect-token (ls_token) from the post-Connect callback

⌘I