Retrieving external account history

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.

Parameter

Description

Type

start_date

String

Retrieve 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_date

String

Retrieve account history up until this date in ISO 8601 YYYY-MM-DD format, for example 2021-10-15. Defaults to today's date.

count

int32

Number of transactions to retrieve, between 1 and 500. Default is 100.

offset

int32

Number 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"
}

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.

Attribute

Description

transaction_id

Unique ID of the transaction.

state

pending or completed.

previous_transaction_id

For completed transactions, this is the ID of the pending transaction where applicable.

transaction_type

One of:

  • `online`—transactions made online
  • `in store`—transactions made at a physical location
  • `other`—transactions related to banks, such as fees or deposits

amount

The signed amount of the settled transaction. Positive values mean money moved out of the account and negative values mean money moved into the account.

currency

The ISO currency code of the transaction.

created_time

The date the transaction was authorized in YYYY-MM-DD format using UTC, for example 2021-08-10.

updated_time

The date the transaction occurred or was completed in YYYY-MM-DD format using UTC, for example 2021-08-31.

statement_descriptor

The transaction description or merchant name.

mcc_description

The description of the most granular MCC code known.

merchant_name

The merchant name retrieved from the statement_descriptor.

merchant_address

The street address where the transaction occurred.

merchant_city

The city where the transaction occurred.

merchant_state

The state or region where the transaction occurred.

merchant_postal_code

The postal code where the transaction occurred.

merchant_country

The ISO country code for where the transaction occurred.

merchant_lat

The geographic latitude where the transaction occurred.

merchant_long

The geographic longitude where the transaction occurred.

merchant_store_number

The 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.


Did this page help you?