# Connections URL: https://www.quiltt.dev/api/connections Description: Learn how to manage Connections with GraphQL. Discover how to fetch, update or disconnect Connections. Navigation: api → connections Tags: API, Core Resources Content Length: 13k characters A **Connection** in Quiltt serves as the primary way to ingest and sync financial data associated with one of your Profiles. Connections are typically created from a data source like Finicity, MX or Plaid, and provide access to account information, transactions and other data, depending on the provider and Connection configuration. After a Connection is created, Quiltt automatically ingests permissioned data, keeps it in sync, and makes its data available via the GraphQL API. Metadata Note: ## Schemas & Types Profile GraphQL Note: ## GraphQL Queries ### `connection` Looks up a specific Connection by its ID: GraphQLRequest: Query: ```graphql query { connection(id: "conn_12tgD1WgzFgsy9fqKpW9b3") { id provider status institution { name logo {url} } accounts [id name] } } ``` Response: ```json { "data": { "connection": { "id": "conn_12tgD1WgzFgsy9fqKpW9b3", "provider": "MX", "status": "SYNCED", "institution": { "name": "MX Bank", "logo": ["url": "https://cdn.quiltt.io/..."] }, "accounts": [ ["id": "acct_12tgD1YBOnVPMw1oKlWj6b", "name": "Mortgage"], ["id": "acct_12tgD1YP33AwEvbdmSrcRY", "name": "Credit Card"], ... ] }, } } ``` ### `connections` Lists the Connections associated with the Profile: GraphQLRequest: Query: ```graphql query { connections { id provider status institution { name logo {url} } accounts [id name] } } ``` Response: ```json { "data": { "connections": [ { "id": "conn_12tgD1WgzFgsy9fqKpW9b3", "provider": "MX", "status": "SYNCED", "institution": { "name": "MX Bank", "logo": ["url": "https://cdn.quiltt.io/..."] }, "accounts": [ ["id": "acct_12tgD1YBOnVPMw1oKlWj6b", "name": "Mortgage"], ["id": "acct_12tgD1YP33AwEvbdmSrcRY", "name": "Credit Card"] ] }, { "id": "conn_12tErBquPaGw6diZp8j801", "provider": "FINICITY", "status": "SYNCED", "institution": { "name": "FinBank", "logo": ["url": "https://cdn.quiltt.io/..."] }, "accounts": [ ["id": "acct_12tErBqz5oPva4qlsZ9Po8", "name": "Checking"], ["id": "acct_12tErBqwklkvjw6AIpeExJ", "name": "Savings"] ] } ] } } ``` The `connections` query supports various filtering options: #### Filter by Status Filters for Connections with specific statuses: ```graphql query { connections(filter: [status: [ERROR_REPAIRABLE, DISCONNECTED]]) [id provider status] } ``` #### Filter by Provider Filters for Connections from specific providers: ```graphql query { connections(filter: [provider: [MX, FINICITY]]) [id provider status] } ``` #### Filter by Metadata Filters for Connections with specific metadata, such as an internal ID: ```graphql query { connections(filter: {metadata: [some_internal_id: "12345"]}) [id provider status metadata] } ``` ## GraphQL Mutations Connection mutations allow you to disconnect or update individual Connections. ### `connectionDisconnect` Disconnect a Connection from its provider, preventing Quiltt from syncing data: GraphQLRequest: Mutation: ```graphql mutation ConnectionDisconnect { connectionDisconnect(input: [id: "conn_12tgD1WgzFgsy9fqKpW9b3"]) { success record {id} } } ``` Response: ```json { "data": { "connectionDisconnect": { "success": true, "record": ["id": "conn_12tgD1WgzFgsy9fqKpW9b3"] } } } ``` ### `connectionUpdate` Updates a Connection with new metadata. This is useful for storing additional information about the Connection, such as a user-friendly name, or an internal ID. Info: Note that updating a Connection's products requires the end-user going through the Connector [Reconnect flow](/connector/reconnect). GraphQLRequest: Mutation: ```graphql mutation ConnectionUpdate($input: ConnectionUpdateInput!) { connectionUpdate(input: $input) { success record [id metadata] } } ``` Variables: ```json { "input": { "id": "conn_12tgD1WgzFgsy9fqKpW9b3", "metadata": ["nickname": "My Special Connection", "internal_id": 12345, "hiddenFromUI": true] } } ``` Response: ```json { "data": { "connectionUpdate": { "success": true, "record": { "id": "conn_12tgD1WgzFgsy9fqKpW9b3", "metadata": ["nickname": "My Special Connection", "internal_id": 12345, "hiddenFromUI": true] } } } } ``` ## GraphQL Subscriptions Connection subscriptions allow you to listen to Connection sync events. ### `connectionSynced` Fires whenever an existing Connection finishes syncing: GraphQLRequest: Subscription: ```graphql subscription ConnectionSynced { connectionSynced(connectionId: "conn_12tgD1WgzFgsy9fqKpW9b3") { connection [id status] } } ``` Response: ```json { "data": { "connectionSynced": { "connection": ["id": "conn_12tgD1WgzFgsy9fqKpW9b3", "status": "ERROR_REPAIRABLE"] } } } ``` ## Webhooks ### `connection.created` This event fires once a new Connection is created on a Profile. ### `connection.synced.successful` This event fires when a Connection is successfully synced with the provider. The Connection status will resolve to `SYNCED`. ### `connection.synced.successful.initial` This event fires once after the first quick sync is completed on a Connection. The Connection status will resolve to `SYNCED`. ### `connection.synced.successful.historical` This event fires after historical data is synced following a successful Connector session. This includes both initial connections and Reconnect flows. The event metadata includes `startDate` and `endDate` indicating the historical period that was synced. The Connection status will resolve to `SYNCED`. ### `connection.synced.errored.repairable` This event fires when a Connection becomes ERROR_REPAIRABLE and requires user action to resume syncing. Have the user complete the Connector Reconnect flow to resolve this error. The Connection status will resolve to `ERROR_REPAIRABLE`. ### `connection.synced.errored.institution` This event fires when the provider is reporting an error with the connected Institution. The Connection status will resolve to `ERROR_INSTITUTION`. ### `connection.synced.errored.provider` This event fires when the Connection provider is reporting an error with the Connection. Inspect the Connection's Remote Data for more information. The Connection status will resolve to `ERROR_PROVIDER`. ### `connection.synced.errored.service` This event fires when an unexpected error occurs attempting to sync the Connection. Visit our [Status page](/status) or contact Quiltt Support for more information. The Connection status will resolve to `ERROR_SERVICE`. ### `connection.disconnected` This event fires when a Connection has been fully disconnected from the provider. The Connection status will resolve to `DISCONNECTED`. If the Connection has been deduplicated, it will be removed from the system. ## Connection statuses Every Connection exposes a `status` field that reflects where it is in its sync lifecycle. Read it on the `connection` or `connections` queries, or subscribe to [Connection webhooks](#webhooks) to react to changes. The following table lists each status, what it means, and what to do when you see it. | Status | Meaning | What to do | |--------|---------|------------| | `INITIALIZING` | Quiltt is setting up the Connection and begins syncing soon. | Wait for the Connection to progress. Data is not available yet. | | `SYNCING` | The Connection is actively syncing data from the provider. | Wait for the sync to finish. The status resolves to `SYNCED` when it completes. | | `SYNCED` | The Connection is up to date with the provider. | No action needed. Data is available through the API. | | `ERROR_REPAIRABLE` | The Connection needs re-authentication before it can resume syncing. | See [Troubleshooting Connection Errors](#troubleshooting-connection-errors). | | `ERROR_INSTITUTION` | The provider is reporting an error from the user's institution. | See [Troubleshooting Connection Errors](#troubleshooting-connection-errors). | | `ERROR_PROVIDER` | The provider is reporting an error with the Connection. | See [Troubleshooting Connection Errors](#troubleshooting-connection-errors). | | `ERROR_SERVICE` | Quiltt hit an internal error while syncing. The Connection retries automatically. | See [Troubleshooting Connection Errors](#troubleshooting-connection-errors). | | `DISCONNECTING` | The Connection is disconnecting from its provider. | Wait for the disconnection to finish. | | `DISCONNECTED` | The Connection is fully disconnected. Existing data remains, but nothing new syncs. | Prompt the user through the Connector [Reconnect flow](/connector/reconnect) to re-establish the Connection. | Info: A Connection can report `SYNCED` while transactions or balances are still missing — for example, when an institution connects but returns no data on the provider that served it. If a Connection stays in `INITIALIZING`, or reaches `SYNCED` without returning the data you expect, contact Quiltt Support with the Connection ID. Some institutions sync more reliably through a different provider, and Support can adjust the provider preference for an institution. ### Initial and historical data loads A Connection's data loads in two phases, which is why a newly connected account often shows recent transactions before its full history appears: 1. **Initial sync** — A fast first sync makes recent accounts, balances, and transactions available. The Connection reaches `SYNCED` and the `connection.synced.successful.initial` webhook fires. 2. **Historical sync** — Quiltt continues backfilling older transactions in the background. When the backfill finishes, the `connection.synced.successful.historical` webhook fires with `startDate` and `endDate` metadata describing the period that was synced. A `SYNCED` status means the latest sync cycle finished — not that every historical transaction has loaded yet. For a new Connection, wait for the `connection.synced.successful.historical` webhook before you expect the full transaction history to be present. To gauge how current an account is, check its `transactedLastOn` field, which reports the date of the most recent synced transaction. #### How long syncing takes Sync latency depends on the institution and the provider (MX, Finicity, Plaid, or Akoya) and is similar in Sandbox and Production. As a rule of thumb: - **Initial sync** (accounts and balances) usually completes within 10 to 20 seconds. - **Historical backfill** usually completes within **1 to 2 minutes**, but can take longer for connections with many accounts or accounts with extensive history. To keep your interface responsive, show the account list by querying GraphQL after the Connector's `onExitSuccess` callback, and load balances and transactions after `connection.synced.successful.initial` fires. We also recommend re-fetching data after `connection.synced.successful.historical` fires to populate the full history. ## Troubleshooting Connection Errors When Connections enter an error state, regular syncing will be interrupted and on-demand API calls like Balance Refreshes will fail until the Connection error is resolved. You can monitor the health of your connections by checking the `Connection.status` field in GraphQL or by subscribing to Connection webhooks. Follow the steps below to troubleshoot and resolve Connection errors based on their status: ### `ERROR_REPAIRABLE` - Have the user complete the Connector [Reconnect flow](https://quiltt.dev/connector/reconnect). ### `ERROR_INSTITUTION` - Have the user confirm that they are: 1. enrolled into the institution's Online Banking 2. can successfully log in 3. their account is not locked - If your Connector uses the **Account Owners** or **Account Statements** products, make sure the user confirms they have enrolled into Electronic Statements delivery. - If the user can log in and their account is not locked but the Connection stays in `ERROR_INSTITUTION`, the institution may have blocked the data provider's access for security reasons. Have the user contact their bank to approve third-party or data-aggregator access, then complete the [Reconnect flow](https://quiltt.dev/connector/reconnect). ### `ERROR_PROVIDER` - Query the Connection's [Remote Data](https://quiltt.dev/api/remote-data) in the GraphQL Explorer (**Profiles** → find Profile by Connection ID → **Launch Explorer**) to understand what error the provider is reporting and what it means. - File a support ticket with the provider. If you manage API Keys through Quiltt, you can contact our support team for assistance. ### `ERROR_SERVICE` - Visit our [Status page](https://status.quiltt.io) to see if there is a temporary service disruption. - Contact Quiltt Support with the Connection ID if the issue is not resolved within 24 hours. ### Provider error codes When a Connection enters `ERROR_INSTITUTION` or `ERROR_PROVIDER`, the underlying data provider (such as Plaid, MX, or Finicity) often attaches its own error code — for example `14006`, `170`, or `2006`. These codes are defined by the provider, not by Quiltt, so the same symptom can surface under different codes depending on which provider served the Connection. To investigate a provider error code: 1. Query the Connection's [Remote Data](/api/remote-data) in the GraphQL Explorer (**Profiles** → find Profile by Connection ID → **Launch Explorer**) or through the API to see the raw error the provider returned, including its code and message. 2. Look up the code in the error reference published by that provider (Plaid, MX, or Finicity) to understand the cause and whether it requires user action. 3. Contact Quiltt Support with the Connection ID if an institution consistently fails on one provider. Some institutions connect more reliably through a different provider, and Support can adjust the provider preference so future Connections use it.