Quiltt Logo

Remote Data

Link to this section#What is Remote Data?

A common argument against using an abstraction layer instead of integrating with the vendor's API directly is that some data field or feature might be hidden from you. 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.

Link to this section#When to use Remote Data

For example, our Transaction records are normalized to a common format. No matter which vendor the source is, the format will be the same. However, if you need to access the raw data we received, you can use our Remote Data endpoint.

Another example: Plaid and MX offer an Identity feature to get information about the owner of a bank account. While we work on exposing this feature in a normalized way, you can already use Remote Data to access the raw data.

Link to this section#How to use Remote Data

Currently, Remote Data is only available via our REST API. We will add access via GraphQL in the coming days.

Link to this section#REST API

Link to this section#General

Remote Data is scoped to corresponding Quiltt records. For example, if you want to access the raw data of a Connection, you need to know the Quiltt ID of the Connection.

For the start, let's assume you have a Connection with the ID conn_123 and want data from MX. You can then use the following endpoint to fetch the Remote Data:

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

The response will be a JSON object that has a documents key. The value of this key is an object with documents grouped by domains and paths. In our example, the domain is api.mx.com and the path is /users/{user_guid}/members/{member_guid} – that shows where we got the data from. The timestamp tells you when the data was fetched. And the body is the response we received.

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

Each domain can have multiple paths. For example, if you have the Identity feature enabled, api.mx.com will also have a /users/{user_guid}/members/{member_guid}/account_owners path once the data is available.

Link to this section#Webhooks

How do you know when the data is available?

You can listen to a webhook event and then fetch the Remote Data of the corresponding record. See the Webhooks guide for more information on webhooks.

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

require 'sinatra'
require 'json'

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

  webhook['events'].each do |event|
    case event['type']
    when 'connection.synced.successful'
      connection_id = event['record']['id']
      puts "Connection with ID #{connection_id} has synced successfully!"

      # Call the Quiltt API to fetch the latest MX Remote Data on the Connection
      endpoint = URI("https://api.quiltt.io/v1/remote/mx/connections/#{connection_id}")
      response = Net::HTTP.get_response(endpoint, Authorization: "Bearer #{ENV['QUILTT_API_KEY']}")

      # Parse the JSON response
      data = JSON.parse(response.body)

      # Fetch the MX "member" GUID from the Remote Data object
      mx_guid = data['documents']['api.mx.com']['/users/{user_guid}/members/{member_guid}']['body']['guid']
      puts "MX Member GUID: #{guid}"
    else
      puts "Unhandled event #{event['type']}"
    end
  end

  status 204
end

Link to this section#API Reference

See the Remote Data API Reference for full documentation of the available endpoints and objects schemas.

Remote Data API Reference

Webhooks →