Remote Data

Link to this section#What is Quiltt Remote Data?

Quiltt's abstraction layer normalizes data from multiple data providers into one standardized format. This makes it trivial to build applications that work with data from multiple providers, or are provider-agnostic.

A common pitfall of abstraction layers is that they can hide useful information from you. For example consider a scenario where you need to access an obscure Transaction field that is only available from a single provider, and is not exposed on Quiltt's normalized data model.

This is where Quiltt's Remote Data comes in!

Remote Data lets you access raw and unmodified data from the data providers you've connected to your environment, just as if you had integrated with each one directly.

Link to this section#When to use Remote Data

Remote Data is a great option to cache the "raw" data from the upstream provider or to help with a migration from a direct integration.

Additionally, it provides a way to access data that is not exposed on Quiltt's normalized data model, such as Account Owners data from Plaid or MX.

Link to this section#How to use Remote Data

Remote Data is available via the Profile GraphQL API, as well as the server-side Platform REST API.

For most use-cases, we recommend accessing Remote Data through the GraphQL API. This approach provides the most flexible experience and is ideally suited for client-side use, as well as for querying specific fields from upstream providers.

Link to this section#Profile GraphQL API

In GraphQL, Remote Data is available via the remoteData field on objects such as Connection, Account, or Transaction. Within remoteData, you can access the payloads for the supported providers, via corresponding fields such as mx, plaid or fingoal.

For example, here's how you can get MX's "Member" data for your Connections:

{
  connections {
    id
    provider
    remoteData {
      mx {
        connection {
          timestamp
          response {
            guid
            name
            isOauth
            userGuid
          }
        }
      }
    }
  }
}

Link to this section#GraphQL API Reference

Link to this section#Platform REST API

In the Platform API, Remote Data is scoped to its corresponding Quiltt record. For example, if you want to access the raw data of a Connection, you would supply the Quiltt ID of the Connection.

Link to this section#Connection Example

Let's assume you have a Connection with the ID conn_12345 and want to get MX's corresponding "Member" data. You can use the following endpoint:

GEThttps://api.quiltt.io/v1/remote/mx/connections/conn_12345

The response will be a JSON object with a documents key. The value is an object with individual documents grouped by domain and path. Each path returns an object with a timestamp (when the data was fetched) and a body (the response Quiltt received)

{
  "...": "...",
  "connectionId": "conn_12345",
  "documents": {
    "api.mx.com": {
      "/users/{user_guid}/members/{member_guid}": {
        "body": {
          "guid": "MBR-12345",
          "name": "MX Bank (Oauth)",
          "isOAuth": true,
          "userGuid": "USR-12345",
          "...": "..."
        },
        "timestamp": "2023-05-06T00:00:00Z"
      }
    }
  }
}

Each domain can have multiple paths. For example, if you have the Account Owners feature enabled on the Connection, api.mx.com will also have a /users/{user_guid}/members/{member_guid}/account_owners path. The body of this path will contain the Account Owners data.

Link to this section#API Reference

Link to this section#Webhooks

How do you know when Remote Data is available?

You can listen to a corresponding webhook event (i.e. connection.synced.successful) and then fetch the Remote Data of the when it's received.

Link to this section#Example using the Platform REST API

For now, let's listen to connection.synced.successful and fetch the MX Remote Data about the Connection, using a simple Ruby script.

require 'sinatra'
require 'json'

QUILTT_API_KEY = ENV['QUILTT_API_KEY']
DOCUMENT_PATH  = '/users/{user_guid}/members/{member_guid}'

# Using Sinatra
post '/quiltt_webhook' do
  webhook = JSON.parse(payload)

  webhook['events'].each do |event|
    event_type = event['type']

    if event_type == 'connection.synced.successful'
      connection_id = event['record']['id']

      # Call the REST endpoint to fetch the latest MX Remote Data on the Connection
      response = Net::HTTP.get_response(
        "https://api.quiltt.io/v1/remote/mx/connections/#{connection_id}",
        Authorization: "Bearer #{QUILTT_API_KEY}"
      )
      data = JSON.parse(response.body)

      # Fetch the MX "member" GUID from the Remote Data object
      member_document = data['documents']['api.mx.com'][DOCUMENT_PATH]
      mx_guid         = member_document['body']['guid']
      puts "MX Member GUID: #{mx_guid}"
    end
  end

  status 204
end

See the Webhooks guide for more information on how to set up and use webhooks.