Skip to main content
A client links Chase, and three months later they open a second checking account under the same Chase login. An Account exists in LedgerSync once the source returns it and LedgerSync saves it. The call to make depends on the connection’s source.
You can read the source off the connection id: con_MX_1224, con_FDE_882, con_FINICITY_41294. See The two id formats.

​
The short answer

On a Finicity connection, the v3 POST /connections/{id}/refresh updates the accounts LedgerSync already holds. It does not import missing accounts or ask the client to share additional ones. Repeated refresh calls do not perform account selection.

​
Why Finicity is different

A refresh cannot grant access to an account the client has not shared. MX and FDE refresh paths also import newly returned accounts. The v3 Finicity refresh path updates stored accounts; use Full Connect when the client wants to share another account. Mastercard distinguishes Full Connect, Lite, and Fix. Full Connect includes account management. Connect Fix handles connection repair, such as credentials or MFA that need attention.

​
Finicity: open Full Connect for the existing client

Call POST /v3/clients/{client_id}/connections using the client who owns the existing connection and the bank’s v3 catalog institution_id. Routing selects the source; when it selects Finicity, this opens Full Connect using the client’s existing Finicity customer. Starting this session does not force a new stored connection. Choose the existing bank in the widget and use its add-account option, such as “Add another Chase account”. When Mastercard returns the same institution login, LedgerSync reuses the existing con_FINICITY_* connection. Existing accounts with the same provider account IDs keep their LedgerSync account rows and IDs; a newly shared account receives a new acc_FINICITY_* ID.
Earlier instructions on this page incorrectly recommended /reauthorize for adding accounts to a healthy Finicity connection. That endpoint uses Connect Fix. It can return a valid URL and then show “No action required” because there is nothing to repair. HTTP 200 does not mean account selection will appear. Use Full Connect for account addition.
1

Start a session for the existing client

Use the same client_id; do not create another Client. Supply the bank’s ins_... identifier from GET /v3/institutions, not the existing con_... identifier.
Replace the example IDs with your client’s and institution’s actual IDs. The response is 202 Accepted with an operation_id. There is no source or existing connection_id field to send in this request. An optional allowlisted redirect_url returns the browser to your app; see Redirect flow.
2

Read the operation and open widget_url

Read GET /v3/operations/{operation_id} until it succeeds or fails. On success, open result.connection.action.widget_url from the Finicity result. Use result.connection.source to check which source routing selected.
Operation succeeded means the widget URL is ready. It does not mean the client completed account selection or that new accounts have been saved. The returned con_<uuid> is a session placeholder, not a new canonical bank connection ID. Keep your existing con_FINICITY_* ID; see The two id formats.
Read result.connection.action.expires_at for the widget’s expiry. The separate repair link’s lifetime does not apply to this URL.
The widget URL grants access to the hosted session. Share it through a trusted channel and keep it out of application logs.
3

Add an account under the existing bank

In Full Connect, select the existing bank and its add-account option. For example, the existing Chase account list includes “Add another Chase account”. Complete any bank authentication or consent steps and share the additional account. The screens and available accounts depend on the institution; an OAuth bank may handle selection on its own site.
4

Re-list accounts and diff

After the client completes the hosted session, allow time for LedgerSync to save the accounts, then re-read GET /v3/accounts?client_id=... and compare account IDs with your pre-session snapshot, as below. Do not wait for the operation’s placeholder ID to change.
Connection reuse depends on the returned institution login. Linking a different bank login, or routing through a different source, can produce another connection and new account IDs. List accounts for the whole client and inspect their connection_id rather than treating the initiate endpoint’s name or placeholder as proof that a second connection was created.
Start a session when the client asks to add an account. Wait for them to complete it instead of repeatedly minting URLs. Completing a session triggers bank aggregation and may fetch statements, so it should not run on a timer.

​
When to use reauthorize

Use POST /v3/connections/{connection_id}/reauthorize when an existing connection needs repair. It takes no body; send Content-Length: 0. The response contains action.reauth_url and action.expires_at. That repair link can be reopened until it expires. Treat it as a bearer link and share it only through a trusted channel. See Handling failed and disconnected for the response example. For some institutions, including American Express, a Finicity repair can route through MX. Check the repair response’s source: accounts linked through MX have new connection and account IDs, while the original Finicity connection keeps its old ones. List by client_id across sources in that case. This repair behavior is separate from the Full Connect account-addition flow above.

​
MX and FDE: a refresh is enough

On MX, a refresh triggers a member aggregation, and the aggregation result re-reads the member’s whole account list and inserts anything unknown. On FDE, a refresh re-runs extraction and inserts sub-accounts it has not seen. In both cases the new account lands on the same connection, so your con_ id is unchanged and only the new account carries a new acc_ id.
You get 202 Accepted and an operation_id. The pull is asynchronous, and account.refresh.completed fires when it lands. See Keeping data fresh.
Do not send an MX or FDE client through reauthorize to add an account. It puts them through a re-login for something a plain refresh does on its own, with no client interaction at all. On MX the scheduled aggregation would have picked it up even without the refresh.

​
Detect the new account: re-list and diff

There is no v3 account-added webhook. connection.active is not a reliable account-addition signal: it may be absent or emitted again without proving the account set changed. account.refresh.completed tells you a refresh finished. Compare account lists to determine whether an account arrived.
1

Snapshot the ids you hold

Before you refresh or open the widget, record the set of id values from GET /v3/accounts?client_id=.... Page through with next_cursor until has_more is false (see Pagination).
2

Re-list after the flow

Read every page again. Listing by client_id alone also catches accounts on a new connection if the bank login or source changed. Use connection_id only when you deliberately want to limit the result to that connection.
3

Diff on id

Any acc_ ID in the new list that is not in your snapshot is a newly observed LedgerSync account. Persist it, then read its transactions and statements as they become available. Repeating the ID comparison does not add the same record twice. A new ID on another connection can represent a bank account you already know, so do not assume it is a newly opened bank account.
When to run the second read:
  • MX and FDE have a cue. Re-list when account.refresh.completed arrives for that connection.
  • Finicity has no dedicated account-added event. Re-list after the client completes the widget or returns to your app, allowing time for account ingestion. If needed, repeat account reads with backoff for a bounded period; do not start another hosted session as a polling mechanism.

​
What does not work

  • Using Finicity /reauthorize as an account picker. Connect Fix can end with “No action required” on a healthy connection.
  • Refreshing a Finicity connection to discover missing accounts. The v3 refresh updates accounts already attached to the connection.
  • Treating operation success or connection.active as proof of addition. Read and compare accounts after the client completes the session.
  • Treating every initiate call as a new stored connection. The Full Connect flow reuses a matching existing bank login. Choosing a different login can create another connection, so inspect the returned account identities before importing overlapping transaction history.

Connection lifecycle

Statuses, reauthorize vs re-initiate, and the two id formats.

Keeping data fresh

What a refresh does, and what it does not do, per source.

Webhooks

The full event catalog, and what it deliberately does not contain.

Connect a bank

The hosted link and the initiate to active walkthrough.