Connectors

Build a production-ready connector that uses multiple data aggregators (Plaid, MX, Finicity, Akoya) for better reliability and coverage.

Time: ~30 minutes Level: Intermediate Framework: Next.js

Link to this section#Why Multiple Aggregators?

Single-aggregator approaches have limits:

• Service outages disrupt all users
• Coverage gaps for certain banks
• Regional availability issues
• Vendor lock-in risks

Quiltt's unified API lets you use multiple aggregators while writing code once.

Link to this section#Prerequisites

• Quiltt Dashboard account
• Basic GraphQL knowledge (see guide)
• Node.js 18+ installed

New to financial data aggregation? We'll explain key concepts as we go.

Link to this section#Step 1: Understand Available Aggregators

Quiltt supports four major aggregators, each with different strengths:

Aggregator	Best For
Plaid	Developer-friendly APIs, major institutions
MX	Credit unions, smaller regional banks (US/Canada)
Finicity	Direct OAuth, payments, lending
Akoya	Direct OAuth to top 100+ US banks

Key differences:

• Coverage: Regional vs national banks
• Products: Account verification, transactions, investments
• Features: Real-time updates, categorization accuracy

You don't need to pick one—Quiltt lets users choose, and your code stays the same.

Link to this section#Step 2: Set Up Your Project

Create a Next.js project:

Install dependencies:

Add credentials from the Dashboard:

Initialize in your root layout:

Link to this section#Step 3: Implementing Multi-Aggregator Connector

Link to this section#3.1 Setting Up Your Connector

Before writing any code, you'll need to configure your connector in the Quiltt Dashboard. This will determine which aggregators and products are available to your users.

1. Visit the Quiltt Dashboard
2. Select your environment (sandbox or production)
3. Create a new connector or edit an existing one
4. Configure the connector:
   1. Set up your Authentication configuration
   2. Set up your Enrollment configuration
   3. In the Connect section:
      • Enable at least two aggregators (e.g., MX and Plaid)
      • Select at least one required product (e.g., ACCOUNT_BALANCES_AND_TRANSACTIONS)
   4. For the purposes of this tutorial, set up the ExitRedirect section to:
      • Set the Redirect URL to http://localhost:3000/login
      • Enable the option for Send Token

Link to this section#3.2 Add the Connector to your Project

Let's implement the core connection components:

The ConnectAccounts component provides a general-purpose button that launches the Quiltt connector dialog, allowing users to connect any supported financial institution:

The PrefilledConnector component demonstrates how to pre-select a specific institution (Chase in this example) for a more streamlined connection experience:

Link to this section#3.3 Handling Authentication

After a successful connection, the Quiltt Connector redirects users to your login page with an authentication token. Let's implement the login handler:

After implementing this login page:

1. The connector redirects to http://localhost:3000/login?token={authToken}
2. useQuilttSession processes and stores the token
3. Users are redirected to /connections
4. Subsequent API requests use this token for authentication

This completes the connection flow and prepares us for accessing financial data in the next section.

Link to this section#Step 4: Accessing Data

The journey from initiating a connection to accessing financial data involves several key steps. Let's break this down into a clear process.

Link to this section#4.1 Connection Events

The Quiltt Connector SDK provides a comprehensive callback system that lets you track every step of the connection process. These events are crucial for implementing a robust multi-aggregator strategy, as they allow you to:

1. Monitor which aggregator was selected for the connection
2. Track the success rate of different aggregators
3. Handle connection failures gracefully
4. Manage the user experience throughout the connection flow

Here's a robust implementation of a connection manager:

The key events you'll want to handle are:

• Open: Triggered when the connector modal opens
• Load: Fired when an aggregator is selected and loaded
• ExitSuccess: Indicates a successful connection, providing the connectionId
• ExitAbort: Triggered if the user cancels the process
• ExitError: Fired if there's an error during connection

Link to this section#4.2 Account Data

The @quiltt/react package provides hooks for handling data fetching and caching through GraphQL. The primary hooks you'll use are:

• useQuery: For fetching data
• useSubscription: For real-time updates
• useQuilttClient: For direct cache access and modifications

These hooks provide several powerful features:

• Automatic retry logic for failed requests
• Request batching for better performance
• Built-in error handling
• Real-time updates via GraphQL subscriptions
• Smart request caching

Link to this section#4.3 Displaying Accounts

Now we can create our accounts list component that handles both initial data loading and real-time updates:

Link to this section#4.4 Real-Time Updates

Quiltt provides real-time updates through GraphQL subscriptions. Here's how to implement comprehensive real-time functionality:

This implementation provides several benefits for a multi-aggregator strategy:

• Real-Time Updates: Get immediate notifications of data changes
• Connection Monitoring: Track connection health across all aggregators
• Sync Progress: Monitor data synchronization progress
• Automatic Cache Updates: Keep UI in sync with backend data
• Resource Optimization: No polling required

Link to this section#4.5 Best Practices

When working with multi-aggregator connections, follow these best practices:

1. Cache Appropriately: Each aggregator has different rate limits and update frequencies
2. Handle Throttling: Implement exponential backoff for retries
3. Optimize Batch Operations: Group requests when possible
4. Monitor Performance: Track response times and success rates per aggregator

By following this structured approach to data access, you'll be able to maintain reliable connections across multiple aggregators while providing a smooth user experience.

Link to this section#4.6 Integration Pages

The home page (./src/app/page.tsx) serves as the entry point for users to initiate new connections:

The connections page (./src/app/connections/page.tsx) provides a dashboard view of all connected accounts and their current status:

The connection details page (./src/app/connections/[id]/page.tsx) shows detailed information for a specific connection, including all linked accounts and repair options if needed:

Link to this section#Step 5: Error Handling and Connection Maintenance

Financial data connections can become disrupted for various reasons:

1. Authentication Changes

   • Password updates
   • Multi-factor authentication changes
   • Security question modifications
   • Token expiration

2. Institution Changes

   • API updates
   • Security protocol changes
   • Service migrations
   • Backend system maintenance

3. Aggregator Issues

   • Service disruptions
   • API deprecations
   • Rate limiting
   • Data format changes

Maintaining reliable connections requires robust error handling and repair capabilities. Let's implement comprehensive error handling:

Link to this section#5.1 Connection Status Types

First, we'll define our connection status handling using the types generated from our GraphQL schema:

Link to this section#5.2 Status Display Component

Let's create a reusable component to display connection status:

Link to this section#5.3 Best Practices for Error Handling

1. Proactive Monitoring: Monitor connection statuses and handle repairs before users encounter issues
2. Clear Communication: Always show current connection status and provide clear next steps
3. Automatic Recovery: Implement automatic retry logic for transient failures
4. State Management: Track repair attempts and connection history
5. Error Logging: Log errors with proper context for debugging and support
6. User Guidance: Include clear instructions for user-actionable items

Link to this section#Conclusion

Implementing a multi-aggregator strategy with Quiltt is like building a resilient financial data infrastructure. By following this guide, you've created:

• A smart routing system for optimal aggregator selection
• Resilient connection management across providers
• Adaptive feature support that maximizes capabilities

The implementation provides:

• A clear entry point for connecting accounts
• A dashboard view of all connections
• Detailed views of individual connections
• Automatic error detection and repair flows
• Real-time connection status monitoring

Link to this section#Next Steps

Continue Learning:

• GraphQL Tooling Tutorial - Set up type-safe GraphQL with code generation
• Account Statements Tutorial - Fetch and display account statements

Related Tutorials:

• Authentication Tutorial - Session token setup and management

Reference Documentation:

• Connector SDK documentation - Complete SDK reference for all platforms
• Connector Reconnect flow - Repair broken connections
• Webhooks documentation - Real-time event notifications
• Integration guides - Provider-specific configurations