Integration Paths
This page covers the architectural decisions platforms make when integrating the Connect Suite.
For component technical reference, see Account Linking and Account Summary.
For end-to-end user workflows, see the advisor aggregation workflow and the investor aggregation workflow.
Key integration decisions
Whether you are integrating aggregation into an advisor-facing platform, a client-facing portal, you will be working with two components: Account Linking and Account Summary.
The two components create an end-to-end aggregation workflow. Account Linking is where connections get established. The user selects a financial institution, authenticates, and consents. That process triggers the first on-demand aggregation and is what makes data available on a daily basis going forward. Account Summary is the ongoing management surface. Users go there to check connection status, troubleshoot errors, re-authenticate a broken connection, or add and remove accounts.
When both components are embedded together, Account Summary acts as the primary controlling surface. User actions in Account Summary fire events that the parent page relays to Account Linking, which launches the appropriate workflow. The parent page provides the coordination between the two. Most platforms embed both components and customize through the available configuration options. If you need greater control over the UI or how the aggregation experience is delivered to your users, you can peel off parts of this workflow and own them yourself through the API rather than embedding the UI components.
Component | Workflow layer | Platform can build its own UI |
|---|---|---|
Account Summary |
| Yes |
Account Linking |
| Yes |
Account Linking |
| No |
1. Account management
By default, Account Summary provides a complete interface for viewing and managing connections: statuses, account details, error states, and actions like re-authentication.
Platforms that want to control how this data is presented, or integrate it into their existing account views, can use the REST API to retrieve the same data and build a custom experience.
Why own account management
Platforms that own account management have generally done so because they want aggregated account data to live inside an experience they already control. That might mean blending held and held-away accounts into a single view, fitting connection data into an existing accounts or portfolio page, or organizing the information differently than the component does by default.
Even when a platform owns the top-level account management experience, Account Summary can still serve as a dedicated maintenance interface for connection troubleshooting, re-authentication, and error resolution in a settings or connected-institutions area.
Trade-offs
Owning account management means taking on the workflows that Account Summary handles by default. Your platform needs to surface connectivity errors, give users a path to fix broken connections, and prompt re-authentication when credentials expire. Each of these maps to a specific Account Linking invocation. The range of error types and asynchronous states is the same set that Account Summary manages out of the box.
How to implement
When you own account management, you implement Account Linking as a standalone component without Account Summary. Instead of the Suite integration pattern where Account Summary fires accountSetup events to coordinate with Account Linking, your parent page invokes Account Linking directly by setting the route attribute.
The standalone integration path is documented in the Account Linking development guide. Your platform needs to reconstruct the workflows that Account Summary provides by default:
- Adding a new connection: invoke Account Linking with
/add-account - Editing an existing credential: invoke with
/edit-credential;credentialId=<credentialIdValue> - Tracking in-progress connections: aggregation runs asynchronously after a connection is initiated. Your platform needs to reflect that intermediate state, poll for completion, and refresh with the latest data once the process resolves.
- Surfacing and categorizing errors: different error types require different user actions. Some require re-authentication, some require the user to take action on the financial institution's website, and some are transient and resolve on their own. Your platform needs to interpret these states and route the user to the correct resolution path, which in most cases means invoking Account Linking with the right route parameters.
- Discovering additional accounts on an existing credential: invoke with
/discover-accounts;credentialId=<credentialIdValue>
The following endpoints return the core data surfaced in the Account Summary component's main view:
- Investor:
GET /api/v1/credentials/accounts/summary - Advisor:
GET /api/v1/credentials/summary
2. Financial institution selection
The first step in the Account Linking workflow is financial institution selection, where the user searches for and selects the institution they want to connect. The built-in selection step offers two levels of configuration. First, you can choose which financial institutions appear as featured tiles on the initial screen. Second, you can exclude specific financial institutions from the full network list, which includes all supported institutions by default. Both are statically configured for your firm. Search behavior, display logic, and the selection interface itself are managed by the component.
Platforms that need more control over this step can bypass it entirely and handle financial institution selection themselves.
Why own financial institution selection
Platforms that own this step generally do so because they want more control over what their users see. That might mean limiting the list to a relevant subset, rolling out support for new institutions incrementally, or routing users across multiple aggregation vendors from a single search experience.
How to implement
You build a search and selection interface that presents your users with the financial institutions you want to make available. The institution list and its metadata are accessible through the REST API. When the user selects an institution, you invoke Account Linking with that institution's identifier on the route attribute, and the component picks up directly at the authentication step.
/add-account;fiId=<FIIdValue>
See the Account Linking attribute reference for the full set of route parameters.
3. The linking flow
Financial institutions and the ways they grant access to data change regularly. Maintaining an authorization experience that keeps pace with those changes across a large number of financial institutions is a significant engineering burden. To protect the user experience and aggregation reliability, we require that platforms use the Account Linking component for this step rather than building their own.
Additional documentation
The default integration path, where both components are embedded together, is covered in the Connect Suite development guide.
If you are owning financial institution selection, account management, or both, you will need the following in addition to the development guide:
- Introduction to ByAllAccounts Connect Account Linking documents the standalone Account Linking integration path, where Account Linking is implemented without Account Summary.
- REST API Guide documents the API endpoints for investor aggregation.
- REST API - Connect Suite for Advisors documents the API endpoints for advisor aggregation.
Updated 7 days ago