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

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

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.

Introduction

📘Using this API for the first time

Retrieving an external account history

📘Note

Transaction format

Account history webhook

Retrieving balances for a Brand's accounts

📘
Using this API for the first time

📘
Note