Connections

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 will automatically ingest permissioned data, keep it in sync, and make its data available via the GraphQL API.

Link to this section#Schemas & Types

Link to this section#GraphQL Queries

Link to this section#connection

Looks up a specific Connection by its ID:

query {
  connection(id: "conn_12tgD1WgzFgsy9fqKpW9b3") {
    id
    provider
    status
    institution {
      name
      logo {
        url
      }
    }
    accounts {
      id
      name
    }
  }
}

{
  "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"
        },
        ...
      ]
    },
  }
}

Link to this section#connections

Lists the Connections associated with the Profile:

query {
  connections {
    id
    provider
    status
    institution {
      name
      logo {
        url
      }
    }
    accounts {
      id
      name
    }
  }
}

{
  "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:

Link to this section#Filter by Status

Filters for Connections with specific statuses:

query {
  connections(filter: {status: [ERROR_REPAIRABLE, DISCONNECTED]}) {
    id
    provider
    status
  }
}

Link to this section#Filter by Provider

Filters for Connections from specific providers:

query {
  connections(filter: {provider: [MX, FINICITY]}) {
    id
    provider
    status
  }
}

Link to this section#Filter by Metadata

Filters for Connections with specific metadata, such as an internal ID:

query {
  connections(filter: {metadata: { some_internal_id: "12345" }}) {
    id
    provider
    status
    metadata
  }
}

Link to this section#GraphQL Mutations

Connection mutations allow you to disconnect or update individual Connections.

Link to this section#connectionDisconnect

Disconnect a Connection from its provider, preventing Quiltt from syncing data:

mutation ConnectionDisconnect {
  connectionDisconnect(input: { id: "conn_12tgD1WgzFgsy9fqKpW9b3" }) {
    success
    record {
      id
    }
  }
}

{
  "data": {
    "connectionDisconnect": {
      "success": true,
      "record": {
        "id": "conn_12tgD1WgzFgsy9fqKpW9b3"
      }
    }
  }
}

Link to this section#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.

mutation ConnectionUpdate($input: ConnectionUpdateInput!) {
  connectionUpdate(input: $input) {
    success
    record {
      id
      metadata
    }
  }
}

{
  "input": {
    "id": "conn_12tgD1WgzFgsy9fqKpW9b3",
    "metadata": {
      "nickname": "My Special Connection",
      "internal_id": 12345,
      "hiddenFromUI": true
    }
  }
}

{
  "data": {
    "connectionUpdate": {
      "success": true,
      "record": {
        "id": "conn_12tgD1WgzFgsy9fqKpW9b3",
        "metadata": {
          "nickname": "My Special Connection",
          "internal_id": 12345,
          "hiddenFromUI": true
        }
      }
    }
  }
}

Link to this section#GraphQL Subscriptions

Connection subscriptions allow you to listen to Connection sync events.

Link to this section#connectionSynced

Fires whenever an existing Connection finishes syncing:

subscription ConnectionSynced {
  connectionSynced(connectionId: "conn_12tgD1WgzFgsy9fqKpW9b3") {
    connection {
      id
      status
    }
  }
}

{
  "data": {
    "connectionSynced": {
      "connection": {
        "id": "conn_12tgD1WgzFgsy9fqKpW9b3",
        "status": "ERROR_REPAIRABLE"
      }
    }
  }
}

Link to this section#Webhooks

Link to this section#connection.created

This event fires once a new Connection is created on a Profile.

Link to this section#connection.synced.successful

This event fires when a Connection is successfully synced with the provider. The Connection status will resolve to SYNCED.

Link to this section#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.

Link to this section#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.

Link to this section#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.

Link to this section#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.

Link to this section#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.

Link to this section#connection.synced.errored.service

This event fires when an unexpected error occurs attempting to sync the Connection. Visit our Status page or contact Quiltt Support for more information. The Connection status will resolve to ERROR_SERVICE.

Link to this section#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.

Link to this section#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 to react to changes. The following table lists each status, what it means, and what to do when you see it.

Link to this section#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 below steps to troubleshoot and resolve Connection errors based on their status:

Link to this section#ERROR_REPAIRABLE

• Have the user complete the Connector Reconnect flow.

Link to this section#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.

Link to this section#ERROR_PROVIDER

• Inspect the Connection's Remote Data in the Dashboard 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.

Link to this section#ERROR_SERVICE

• Visit our Status page 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.

Link to this section#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. Inspect the Connection's Remote Data in the Dashboard 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.