Retrieving external account history

How to retrieve the history on a linked external account.

📘

Note

To get external account history, you need to use the v0 APIs.

Introduction

You can retrieve an account transaction history for external accounts that have been successfully linked to a customer using Plaid Link. Depending on the external financial institute and the duration of time that the account has been open, up to 24 months of transaction data can be retrieved.

You can't retrieve history for an external account that has been linked but which is not verified.

In a single paginated response, you can retrieve up to 500 sequentially ordered transactions.

📘

Using this API for the first time

When this endpoint is called for an account for the first time, a full transaction history query starts processing. This takes a minute or two to complete and only occurs once. When this is complete, any subsequent queries are returned immediately.

Retrieving an external account history

To retrieve an account's history, use GET /accounts/{account_id}/history and provide optional query parameters as shown in the table below.

ParameterDescriptionType
start_datestringRetrieve account history starting at this date in ISO 8601 YYYY-MM-DD format, for example 202-01--1. Default is 30 days prior to end_date.
end_datestringRetrieve account history up until this date in ISO 8601 YYYY-MM-DD format, for example 2021-10-15. Defaults to today's date.
countint32Number of transactions to retrieve, between 1 and 500. Default is 100.
offsetint32Number of transactions to skip. Default is 0.

An example of a request to retrieve an account history is shown below.

curl --request GET \
     --url 'https://sandbox.bond.tech/api/v0/accounts/9dc86a8a-4c12-4107-84a8-e7cf6a76586f/history?start_date=2020-01-01&end_date=2021-07-31&count=50&offset=0' \
     --header 'Accept: application/json'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/accounts/9dc86a8a-4c12-4107-84a8-e7cf6a76586f/history?start_date=2020-01-01&end_date=2021-07-31&count=50&offset=0")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'

response = http.request(request)
puts response.read_body
const options = {method: 'GET', headers: {Accept: 'application/json'}};

fetch('https://sandbox.bond.tech/api/v0/accounts/9dc86a8a-4c12-4107-84a8-e7cf6a76586f/history?start_date=2020-01-01&end_date=2021-07-31&count=50&offset=0', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://sandbox.bond.tech/api/v0/accounts/9dc86a8a-4c12-4107-84a8-e7cf6a76586f/history"

querystring = {"start_date":"2020-01-01","end_date":"2021-07-31","count":"50","offset":"0"}

headers = {"Accept": "application/json"}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0/accounts/9dc86a8a-4c12-4107-84a8-e7cf6a76586f/history?start_date=2020-01-01&end_date=2021-07-31&count=50&offset=0");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/accounts/9dc86a8a-4c12-4107-84a8-e7cf6a76586f/history?start_date=2020-01-01&end_date=2021-07-31&count=50&offset=0")
  .get()
  .addHeader("Accept", "application/json")
  .build();

Response response = client.newCall(request).execute();

When this API is queried for the first time, you receive a response similar to that shown below.

{
    "account_id": "b3952794-e073-41fc-80c9-18166039bc43",
    "status": "initiated",
    "message": "Transaction query initiated"
}

📘

Note

You need to refresh the external account link if you receive the following message:

{
     "Message":"The login details of this item have changed (credentials, MFA, or required user action) and a user 
      login is required to update this information. Use Link's update mode to restore the item to a good state.",
      "Status": 424,
     "Code": "processor_error",
     "Type": "Processor Error",
}

Webhooks are sent when the full transaction history is ready, as described below in Account history webhook. When the data set is ready, you can send a query again to retrieve transactions.

An example of a response to a successful request for an external account history is shown below.

{
  "account_id": "b3952794-e073-41fc-80c9-18166039bc43",
  "type": "external",
  "balances": {
    "available_balance": 110,
    "current_balance": 110,
    "currency": "USD",
  },
  "total_transactions": 125,
  "transactions": [
    {
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "state": "pending",
      "previous_transaction_id": null,
      "transaction_type": "in store",
      "amount": 2307.21,
      "currency": "USD",
      "created_time": "2017-01-27",
      "updated_time": "2017-01-29",
      "details": {
        "statement_descriptor": "Apple Store",
        "mcc_description": "Computers and Electronics",
        "merchant_name": "Apple",
        "merchant_address": "300 Post St",
        "merchant_city": "San Francisco",
        "merchant_state": "CA",
        "merchant_postal_code": "94108",
        "merchant_country": "US",
        "merchant_lat": 40.740352,
        "merchant_long": -74.001761,
        "merchant_store_number": "1235"
      }
    }
  ]
}

total_transactions is the total number of transactions available within the date range you specified. If this is larger than the size of the transactions array (using any value of count), more transactions are available which can be retrieved using the offset parameter.

For a complete specification and interactive examples, see Get accounts history in the Bond API Reference.

Transaction format

The attributes comprising a transaction in the external account transaction history response are described in the table below.

AttributeDescription
transaction_idUnique ID of the transaction.
statepending or completed.
previous_transaction_idFor completed transactions, this is the ID of the pending transaction where applicable.
transaction_typeOne of:
  • online—transactions made online
  • in store—transactions made at a physical location
  • other—transactions related to banks, such as fees or deposits
amountThe signed amount of the settled transaction. Positive values mean money moved out of the account and negative values mean money moved into the account.
currencyThe ISO currency code of the transaction.
created_timeThe date the transaction was authorized in YYYY-MM-DD format using UTC, for example 2021-08-10.
updated_timeThe date the transaction occurred or was completed in YYYY-MM-DD format using UTC, for example 2021-08-31.
statement_descriptorThe transaction description or merchant name.
mcc_descriptionThe description of the most granular MCC code known.
merchant_nameThe merchant name retrieved from the statement_descriptor.
merchant_addressThe street address where the transaction occurred.
merchant_cityThe city where the transaction occurred.
merchant_stateThe state or region where the transaction occurred.
merchant_postal_codeThe postal code where the transaction occurred.
merchant_countryThe ISO country code for where the transaction occurred.
merchant_latThe geographic latitude where the transaction occurred.
merchant_longThe geographic longitude where the transaction occurred.
merchant_store_numberThe merchant defined store number where the transaction occurred.

Account history webhook

To receive notification when the full account history is available to query, subscribe to the account.history.ready webhook event.

Once you have subscribed to this event and the full transaction history is available, you receive a callback similar to that shown below.

{
    "event": "account.history.ready",
    "account_id": "b3952794-e073-41fc-80c9-18166039bc43",
    "occurred_at": "2021-02-02-00:50:58.484840+00:00"
}

For a description of webhooks, see Webhooks and Webhook events and subscriptions. For a complete specification and interactive examples, see Webhooks in the Bond API Reference.

Retrieving balances for a Brand's accounts

For details regarding retrieving account balances, see Retrieving account balances.