# Remote Data
URL: https://www.quiltt.dev/api/remote-data
Description: Learn how to use Remote Data to access timestamped provider-specific source data.
Navigation: api → remote-data
Tags: API

## What is Quiltt Remote Data?

Quiltt's abstraction layer normalizes data from multiple data providers into one standardized format. This helps you 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's only available from a single provider, and isn't 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.

## 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 isn't exposed on Quiltt's normalized data model, such as Liabilities data from Plaid.

## How to use Remote Data

Remote Data is available via the Profile GraphQL API and the server-side 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 and for querying specific fields from upstream providers.

### 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:

```graphql
{
  connections {
    id
    provider
    remoteData {
      mx {
        connection {
          id
          timestamp
          response [guid
            name
            isOauth
            userGuid]
        }
      }
    }
  }
}
```

#### GraphQL API reference

Profile GraphQL Note:

### REST API

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

#### Connection example

Assume you have a Connection with the ID `conn_14TJiFDKRJlPiBHuukUIlXZ` and want to get MX's corresponding "Member" data. Use the following endpoint:

API Endpoint - GET https://api.quiltt.io/v1/remote/mx/connections/conn_14TJiFDKRJlPiBHuukUIlXZ:

The response is 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).

```json
{
  "...": "...",
  "connectionId": "conn_14TJiFDKRJlPiBHuukUIlXZ",
  "documents": {
    "api.mx.com": {
      "/users/{user_guid}/members/{member_guid}": {
        "id": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4x",
        "body": ["guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4x",
          "name": "MX Bank (OAuth)",
          "isOAuth": true,
          "userGuid": "USR-fa7537f3-48aa-a683-a02a-b18940482f59",
          "...": "..."],
        "timestamp": "2024-05-06T00:00:00Z"
      }
    }
  }
}
```

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

#### API reference

REST API Note:

### Webhooks

How do you know when Remote Data is available?

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

#### Example using the 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.

```ruby
require 'sinatra'
require 'json'

QUILTT_API_KEY_SECRET = ENV['QUILTT_API_KEY_SECRET']
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']

    # This will automatically include the initial and historical sub events
    if event_type.start_with?('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_SECRET}"
      )
      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](/webhooks) for more information on how to set up and use webhooks.