Plaid

Plaid

Plaid Guide

Since FinGoal handles user registration there is no need to add link token creation or exchange. First, you just need to register with the FinSightAPI, then you're ready to send users to the Link Money Gateway with { auth headers } where they'll link their accounts.

Responses from data dumps can be sent via webhooks or you can call for the data manually via the endpoints listed below.

Plaid Endpoints

The Link Money API exposes numerous endpoints for developers to interact with our data in a variety of ways. Broadly speaking, these endpoints can be divided into a couple of categories.

URL Construction

Depending on which endpoint collection, you may only need to access certain endpoint collections and not others. Endpoint construction is essentially:

  1. The Base URL - for example, https://linkmoney-dev.fingoal.com
  2. The endpoint collection's name - In this case, plaid.
  3. The version - each endpoint collection has separate versioning rather than a holistic version control for the entire api - for example, v1.
  4. The endpoint, as specified in each endpoint's documentation.

Some examples include:

https://linkmoney-dev.fingoal.com/v1/plaid/transactions/get
https://linkmoney-dev.fingoal.com/v2/plaid/transactions
https://linkmoney-dev.fingoal.com/v1/plaid/configuration

Since FinGoal handles user registration there is no need to add link token creation or exchange. First, you just need to register with the FinSightAPI, then you're ready to send users to the Link Money Web Portal with your token where they'll link their accounts.

Endpoints are broadly divided into sections described by the index. Each collection of endpoints offers access to a different set of functions. Most developers will only require a small portion of these endpoints to fully integrate with Link Money.

Responses from data dumps can be sent via webhooks or you can call for the data manually via the endpoints listed above.

Some developers who use Link Money API will be coming from another aggregator, Plaid. Though Plaid's functionality is similar to what we're offering, it has a different call structure from our own. In order to minimize friction during the migration process, Link Money API provides endpoints that clone the Plaid structure and receive and return Plaid data.

Items

Items are borrowed from the Plaid terminology. Per their documentation:

"An item represents a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items."

While the LinkMoney API does not use the item system in its underlying data scheme, it still leverages the term in Plaid endpoints to help with transition from the Plaid platform.

Developers can use the Plaid Item endpoints to retrieve items from the LinkMoney API. As with Plaid, these Items will include only data associated with a login from a single institution.

Retrieve An Item.

Endpoint: POST /item/get

Find a single item and return its status.

Parameters

For the Request

NameLocationDescription
Request BodyHeaders
Like Plaid, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual.

Example Request

curl -X POST /item/get \
	-H 'Content-Type: application/json' \
	-H "Authorization: Bearer {access_token}" 

Response

See the Item Model for a full description of the schema.

{
  "item": {
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "update_type": "background",
    "webhook": "/example/hook",
    "consent_expiration_time": null
  },
  "status": {
    "transactions": {
      "last_successful_update": "2019-02-15T15:52:39.000Z",
      "last_failed_update": "2019-01-22T04:32:00.000Z"
    },
    "last_webhook": {
      "sent_at": "2019-02-15T15:53:00.000Z",
      "code_sent": "DEFAULT_UPDATE"
    }
  },
  "request_id": "m8MDnv9okwxFNBV"
}

Remove an Item.

Endpoint: POST /item/remove

Removes a specific item. Note that if the user has accounts with other financial institutions, these will not be removed.

Parameters

For the Request

NameLocationDescription
Request BodyHeaders
Like Plaid, LinkMoney API enables placing the access_token in either the body or the header of requests. The access_token should be user-specific to retrieve information for a single individual.

Example Request

curl -X POST /item/remove \
	-H 'Content-Type: application/json' \
	-H "Authorization: Bearer {access_token}"

Response

Removing an item will respond with a request_id for troubleshooting common problems. ( link to troubleshooting )

{
	"request_id": "c9b50715-d8ab-4e90-bba1-f9d93059c6c0"
}

Institutions

Institutions are organizations that hold user financial data. Developers can see which institutions are available through the LinkMoney platform and what the institution's status is. For particular use cases, developers can search for particular institutions to find details about a certain provider.

Get Details of Supported Institutions.

Endpoint: POST /institutions/get

Find important data about institutions supported in LinkMoney.

Parameters

For the Request

NameLocationDescriptionType
Request Body
The total number of institutions to return. This field is required and limited to 500.
number
Request Body
The number of institutions to skip in pagination.
number

Example Request

curl -X POST /institutions/get \
	-H 'Content-Type: application/json' \
	-H "Authorization: Bearer {access_token}" \
	-d '{ 
		"count": 500,
		"offset": 1000,
	}'

Example Response

For more information about the response, see the model documentation entry on Plaid institutions.

{
  "institutions": [
    {
      "institution_id": "ins_1",
      "name": "Bank of America",
    }
  ],
  "request_id": "tbFyCEqkU774ZGG",
  "total": 11384
}

Get Details of an Institution

Endpoint: POST /institutions/get_by_id

Get the details for a specific financial institution supported by Link Money.

Parameters

For the Request

NameLocationDescription
Request Body
The ID of the institution to get details about.

Example Request

curl -X POST /institutions/get_by_id \
  -H 'Content-Type: application/json' \
	-H "Authorization: Bearer {access_token}" \
  -d '{
    "institution_id": "ins_109512",
  }'

Example Response

{
  "institution": {
    "institution_id": "ins_109512",
    "name": "Houndstooth Bank",
    "status": {
      "item_logins": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.9,
          "error_link_money": 0.01,
          "error_institution": 0.09
        }
      },
      "transactions_updates": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-12T08:22:00Z",
        "breakdown": {
          "success": 0.95,
          "error_link_money": 0.02,
          "error_institution": 0.03,
          "refresh_interval": "NORMAL"
        }
      },
      "auth": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.91,
          "error_link_money": 0.01,
          "error_institution": 0.08
        }
      },
      "balance": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.89,
          "error_link_money": 0.02,
          "error_institution": 0.09
        }
      },
      "identity": {
        "status": "DEGRADED",
        "last_status_change": "2019-02-15T15:50:00Z",
        "breakdown": {
          "success": 0.42,
          "error_link_money": 0.08,
          "error_institution": 0.5
        }
      },
      "investments": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.89,
          "error_link_money": 0.02,
          "error_institution": 0.09
        },
        "liabilities": {
          "status": "HEALTHY",
          "last_status_change": "2019-02-15T15:53:00Z",
          "error_link_money": {
            "success": 0.89,
            "error_plaid": 0.02,
            "error_institution": 0.09
          }
        }
      },
      "investments_updates": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-12T08:22:00Z",
        "breakdown": {
          "success": 0.95,
          "error_plaid": 0.02,
          "error_institution": 0.03,
          "refresh_interval": "NORMAL"
        }
      },
      "liabilities_updates": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-12T08:22:00Z",
        "breakdown": {
          "success": 0.95,
          "error_plaid": 0.02,
          "error_institution": 0.03,
          "refresh_interval": "NORMAL"
        }
      },
      "primary_color": "#004966",
      "url": "https://example-bank.com",
      "logo": null
    }
  },
  "request_id": "m8MDnv9okwxFNBV"
}

Search Institutions

Endpoint: POST /institutions/search

Use query parameters to find up to ten matching institutions.

Parameters

For the Request

NameLocationDescription
Request Body
A string search query to filter down results.

Example Request

curl -X POST /institutions/search \
  -H 'Content-Type: application/json' \
	-H "Authorization: Bearer {access_token}" \
  -d '{
    "query": "Gingham",
  }'

Example Response

{
  "institutions": [
    {
      "institution_id": "ins_118923",
      "name": "Red Platypus Bank - Red Platypus Bank"
    }
  ],
  "request_id": "Ggmk0enW4smO2Tp"
}

Accounts & Transactions

Most user data lives in accounts and transactions. By using these endpoints, developers can access details about user accounts and their associated transactions.

Retrieve Accounts

Endpoint: POST /accounts/get

Retrieve an account summary for any linked items that are not closed and actively carrying a balance.

Parameters

For the Request

NameLocationIs RequiredDescription
Request Body
false
An optional JSON object containing specific parameters to request more specific data. See Options below

Options

NameTypeDescription
String[]
An array of account_ids to retrieve for the Account.

Example Request

curl -X POST /accounts/get \
  -H 'Content-Type: application/json' \
	-H "Authorization: Bearer {access_token}"

Response

{
  "accounts": [
    {
      "account_id": "blgvvBlXw3cq5GMPwqB6s6q4dLKB9WcVqGDGo",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "6PdjjRP6LmugpBy5NgQvUqpRXMWxzktg3rwrk",
      "balances": {
        "available": null,
        "current": 23631.9805,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    },
    {
      "account_id": "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    }
  ],
  "item": {
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "bkVE1BHWMAZ9Rnr"
}

Get Transaction Data

Endpoint: POST /transactions/get

Receive user-authorized transaction data for credit, depository, and some loan-type accounts. For transaction history from investment accounts, use the endpoints instead.

Parameters

For the Request

NameLocationDescriptionRequired
Request Body
An optional object to be used with the request.
Request Body
The earliest date for which data should be returned. Dates should be formatted as YYYY-MM-DD
Request Body
The latest date for which data should be returned. Dates should be formatted as YYYY-MM-DD.

For Options

NameTypeDescription
String[]
A list of the account_ids to retrieve for the item. Note that an error will be returned if a provided account_id is not associated with the item.
number
The number of transactions to fetch. Defaults to 100, and can be set anywhere between 1 and 500.
number
The number of transactions to skip for pagination. The default value is 0.

Example Request

curl -X POST /transactions/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
  "start_date": "2018-01-01",
  "end_date": "2018-02-01",
  "options": {
    "count": 250,
    "offset": 100
  },
}'

Response

{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 110,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "transactions": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "amount": 2307.21,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "category": [
        "Shops",
        "Computers and Electronics"
      ],
      "category_id": "19013000",
      "date": "2017-01-29",
      "datetime": null,
      "authorized_date": "2017-01-27",
      "authorized_datetime": null,
      "location": {
        "address": "300 Post St",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94108",
        "country": "US",
        "lat": 40.740352,
        "lon": -74.001761,
        "store_number": "1235"
      },
      "name": "Apple Store",
      "merchant_name": "Apple",
      "payment_meta": {
        "by_order_of": null,
        "payee": null,
        "payer": null,
        "payment_method": null,
        "payment_processor": null,
        "ppd_id": null,
        "reason": null,
        "reference_number": null
      },
      "payment_channel": "in store",
      "pending": false,
      "pending_transaction_id": null,
      "account_owner": null,
      "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
      "transaction_code": null,
      "transaction_type": "place"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "identity",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "total_transactions": 1,
  "request_id": "45QSn"
}

Refresh Transaction Data

Endpoint: POST /transactions/refresh

Initiate an on-demand extraction to fetch the newest transactions for an Item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur multiple times a day for any Transactions-enabled Item. If changes are discovered after calling this endpoint, LinkMoney will send one of the following webhooks to your specified callback URL:

  • TRANSACTIONS_REMOVED, if removed transactions are detected.
  • DEFAULT_UPDATE, if new transactions are detected. New transactions can also be accessed with the Get Transaction Data endpoint (see above).

— link to Webhooks for Plaid once we have them, since that's going to be a big deal —

Example Request

curl -X POST /transactions/refresh \
 -H 'content-type: application/json' \
	-H "Authorization: Bearer {access_token}" \

Example Response

{
  "request_id": "1vwmF5TBQwiqfwP"
}

Get Categories

Endpoint: POST /categories/get

Get detailed information on categories returned by LinkMoney in Plaid format. You can also refer to the Category Documentation (link to documentation) for a reference on what categories are available in the LinkMoney API.

Example Request

curl -X POST /categories/get \
  -H 'Content-Type: application/json' \
	-H "Authorization: Bearer {access_token}" \
  -d '{}'

Example Response

{
  "categories": [
    {
      "category_id": "10000000",
      "group": "special",
      "hierarchy": [
        "Bank Fees"
      ]
    },
    {
      "category_id": "10001000",
      "group": "special",
      "hierarchy": [
        "Bank Fees",
        "Overdraft"
      ]
    },
    {
      "category_id": "12001000",
      "group": "place",
      "hierarchy": [
        "Community",
        "Animal Shelter"
      ]
    }
  ],
  "request_id": "ixTBLZGvhD4NnmB"
}

Retrieve Account Balances

Endpoint: POST /accounts/balance/get

Retrieve the real-time balance of each of an Item's accounts. While the /accounts/get endpoint does include balance objects in the return data, this endpoint will force an account's balances to refresh, ensuring that the data returned is real0time.

Parameters

For the Request

NameLocationDescription
Request Body
An optional object to filter the results of this call.

Options

NameTypeDescription
String[]
A list of account_ids to retrieve for the item. Defaults to null. An error will be returned if a provided account_id is not associated with the item.
StringYYYY-MM-DDTHH:mm:ssZ
A timestamp indicating the oldest acceptable balance when making a request.

Example Request

curl -X POST /accounts/balance/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
  "options": {
    "account_ids": [String]
  }
}'

Example Response

{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
      "balances": {
        "available": null,
        "current": 410,
        "iso_currency_code": "USD",
        "limit": 2000,
        "unofficial_currency_code": null
      },
      "mask": "3333",
      "name": "Plaid Credit Card",
      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
      "subtype": "credit card",
      "type": "credit"
    },
    {
      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "identity",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "qk5Bxes3gDfv4F2"
}

Investments

Some accounts are not included in traditional accounts calls and have their own endpoints, separate from accounts. Investments are one such account type. Endpoints for Liabilities also have their own separate collection. For every other type of accounts, use the generic Accounts & Transactions endpoint collection.

Get Investment Holdings

Endpoint: POST /investment/holdings/get

Parameters

In the Request Body

NameLocationDescription
Request Body
An optional object to filter the results of this call.

Options

NameTypeDescription
String[]
An array of account_ids to retrieve for the Item. An error will be returned if a provided account_id is not associated with the Item.

Example Request

curl -X POST /investments/holdings/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'

Example Response

{
  "accounts": [
    {
      "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",
      "balances": {
        "available": 43200,
        "current": 43200,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "4444",
      "name": "Plaid Money Market",
      "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
      "subtype": "money market",
      "type": "depository"
    },
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "balances": {
        "available": null,
        "current": 320.76,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "balances": {
        "available": null,
        "current": 23631.9805,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    }
  ],
  "holdings": [
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "cost_basis": 1,
      "institution_price": 1,
      "institution_price_as_of": "2021-04-13",
      "institution_value": 0.01,
      "iso_currency_code": "USD",
      "quantity": 0.01,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 1.5,
      "institution_price": 2.11,
      "institution_price_as_of": null,
      "institution_value": 2.11,
      "iso_currency_code": "USD",
      "quantity": 1,
      "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 10,
      "institution_price": 10.42,
      "institution_price_as_of": null,
      "institution_value": 20.84,
      "iso_currency_code": "USD",
      "quantity": 2,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "unofficial_currency_code": null
    },
    {
      "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",
      "cost_basis": 0.01,
      "institution_price": 0.011,
      "institution_price_as_of": null,
      "institution_value": 110,
      "iso_currency_code": "USD",
      "quantity": 10000,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 23,
      "institution_price": 27,
      "institution_price_as_of": null,
      "institution_value": 636.309,
      "iso_currency_code": "USD",
      "quantity": 23.567,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 15,
      "institution_price": 13.73,
      "institution_price_as_of": null,
      "institution_value": 1373.6865,
      "iso_currency_code": "USD",
      "quantity": 100.05,
      "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
      "unofficial_currency_code": null
    },
    {
      "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
      "cost_basis": 1,
      "institution_price": 1,
      "institution_price_as_of": null,
      "institution_value": 12345.67,
      "iso_currency_code": "USD",
      "quantity": 12345.67,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "unofficial_currency_code": null
    }
  ],
  "item": {
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "l68wb8zpS0hqmsJ",
  "securities": [
    {
      "close_price": 0.011,
      "close_price_as_of": "2021-04-13",
      "cusip": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "Nflx Feb 01'18 $355 Call",
      "proxy_security_id": null,
      "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",
      "sedol": null,
      "ticker_symbol": "NFLX180201C00355000",
      "type": "derivative",
      "unofficial_currency_code": null
    },
    {
      "close_price": 27,
      "close_price_as_of": null,
      "cusip": "577130834",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US5771308344",
      "iso_currency_code": "USD",
      "name": "Matthews Pacific Tiger Fund Insti Class",
      "proxy_security_id": null,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "sedol": null,
      "ticker_symbol": "MIPTX",
      "type": "mutual fund",
      "unofficial_currency_code": null
    },
    {
      "close_price": 2.11,
      "close_price_as_of": null,
      "cusip": "00448Q201",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US00448Q2012",
      "iso_currency_code": "USD",
      "name": "Achillion Pharmaceuticals Inc.",
      "proxy_security_id": null,
      "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",
      "sedol": null,
      "ticker_symbol": "ACHN",
      "type": "equity",
      "unofficial_currency_code": null
    },
    {
      "close_price": 10.42,
      "close_price_as_of": null,
      "cusip": "258620103",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US2586201038",
      "iso_currency_code": "USD",
      "name": "DoubleLine Total Return Bond Fund",
      "proxy_security_id": null,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "sedol": null,
      "ticker_symbol": "DBLTX",
      "type": "mutual fund",
      "unofficial_currency_code": null
    },
    {
      "close_price": 1,
      "close_price_as_of": null,
      "cusip": null,
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": true,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "U S Dollar",
      "proxy_security_id": null,
      "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",
      "sedol": null,
      "ticker_symbol": "USD",
      "type": "cash",
      "unofficial_currency_code": null
    },
    {
      "close_price": 13.73,
      "close_price_as_of": null,
      "cusip": null,
      "institution_id": "ins_3",
      "institution_security_id": "NHX105509",
      "is_cash_equivalent": false,
      "isin": null,
      "iso_currency_code": "USD",
      "name": "NH PORTFOLIO 1055 (FIDELITY INDEX)",
      "proxy_security_id": null,
      "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",
      "sedol": null,
      "ticker_symbol": "NHX105509",
      "type": "etf",
      "unofficial_currency_code": null
    }
  ]
}

Get Investment Transactions

Endpoint: POST /investments/transactions/get

Retrieve user-authorized transaction data for investment accounts. Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift.

Parameters

For the Request

NameLocationDescription
Request Body
The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.
Request Body
The latest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.
Request Body
An optional object to filter the results of this call.

Options

NameTypeDescription
String[]
An array of account_ids to retrieve for the item.
Number
The number of transactions to fetch. Defaults to 100 and can be any number between 1 and 500.
Number
The number of transactions to skip for pagination. Defaults to 0.

Example Request

curl -X POST /investments/transactions/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{
  "start_date": "2018-03-01",
  "end_date": "2018-04-30",
  "options": {
    "count": 250,
    "offset": 100
  }
}'

Example Response

{
  "accounts": [
    {
      "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z",
      "balances": {
        "available": null,
        "current": 320.76,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "5555",
      "name": "Plaid IRA",
      "official_name": null,
      "subtype": "ira",
      "type": "investment"
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "balances": {
        "available": null,
        "current": 23631.9805,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "6666",
      "name": "Plaid 401k",
      "official_name": null,
      "subtype": "401k",
      "type": "investment"
    }
  ],
  "investment_transactions": [
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -8.72,
      "cancel_transaction_id": null,
      "date": "2020-05-29",
      "fees": 0,
      "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
      "iso_currency_code": "USD",
      "name": "INCOME DIV DIVIDEND RECEIVED",
      "price": 0,
      "quantity": 0,
      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
      "subtype": "dividend",
      "type": "cash",
      "unofficial_currency_code": null
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": -1289.01,
      "cancel_transaction_id": null,
      "date": "2020-05-28",
      "fees": 7.99,
      "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",
      "iso_currency_code": "USD",
      "name": "SELL Matthews Pacific Tiger Fund Insti Class",
      "price": 27.53,
      "quantity": -47.74104242992852,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "subtype": "sell",
      "type": "sell",
      "unofficial_currency_code": null
    },
    {
      "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
      "amount": 7.7,
      "cancel_transaction_id": null,
      "date": "2020-05-27",
      "fees": 7.99,
      "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv",
      "iso_currency_code": "USD",
      "name": "BUY DoubleLine Total Return Bond Fund",
      "price": 10.42,
      "quantity": 0.7388014749727547,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "subtype": "buy",
      "type": "buy",
      "unofficial_currency_code": null
    }
  ],
  "item": {
    "available_products": [
      "assets",
      "balance",
      "identity",
      "transactions"
    ],
    "billed_products": [
      "auth",
      "investments"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_12",
    "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "iv4q3ZlytOOthkv",
  "securities": [
    {
      "close_price": 27,
      "close_price_as_of": null,
      "cusip": "577130834",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US5771308344",
      "iso_currency_code": "USD",
      "name": "Matthews Pacific Tiger Fund Insti Class",
      "proxy_security_id": null,
      "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",
      "sedol": null,
      "ticker_symbol": "MIPTX",
      "type": "mutual fund",
      "unofficial_currency_code": null
    },
    {
      "close_price": 10.42,
      "close_price_as_of": null,
      "cusip": "258620103",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US2586201038",
      "iso_currency_code": "USD",
      "name": "DoubleLine Total Return Bond Fund",
      "proxy_security_id": null,
      "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
      "sedol": null,
      "ticker_symbol": "DBLTX",
      "type": "mutual fund",
      "unofficial_currency_code": null
    },
    {
      "close_price": 34.73,
      "close_price_as_of": null,
      "cusip": "84470P109",
      "institution_id": null,
      "institution_security_id": null,
      "is_cash_equivalent": false,
      "isin": "US84470P1093",
      "iso_currency_code": "USD",
      "name": "Southside Bancshares Inc.",
      "proxy_security_id": null,
      "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
      "sedol": null,
      "ticker_symbol": "SBSI",
      "type": "equity",
      "unofficial_currency_code": null
    }
  ],
  "total_investment_transactions": 3
}

Plaid Auth

Auth endpoints are used to obtain the information required to initiate transfer between accounts. These endpoints are designed specifically for developers migrating from Plaid to Link Money, and are designed to follow the Plaid specification for their auth API.

Retrieve Auth Data

Endpoint: POST /v1/plaid/auth/get

Retrieves account and bank information necessary for transfers. Account, Routing, and Wire Routing numbers, as well as account balances (when available).

For the Request

NameLocationIs RequiredDescription
Request Body
True
Access token created for the item
Request Body
False
Optional filter for the response

Options

NameTypeDescription
String[]
List of account_ids to be retrieved

Example Request

curl -X POST /auth/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "access_token": String,
  "options": {
    "account_ids": [String]
  }
}'

Example Response

{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": {
        "available": 100,
        "current": 110,
        "limit": null,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "mask": "9606",
      "name": "Link Money Checking",
      "official_name": "Link Money Silver Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "numbers": {
    "ach": [
      {
        "account": "9900009606",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [
      {
        "account": "111122223333",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "institution": "021",
        "branch": "01140"
      }
    ],
    "international": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "bic": "NWBKGB21",
        "iban": "GB29NWBK60161331926819"
      }
    ],
    "bacs": [
      {
        "account": "31926819",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "sort_code": "601613"
      }
    ]
  },
  "item": {
    "available_products": [
      "balance",
      "identity",
      "payment_initiation",
      "transactions"
    ],
    "billed_products": [
      "assets",
      "auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "m8MDnv9okwxFNBV"
}
{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": {
        "available": 100,
        "current": 110,
        "limit": null,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null
      },
      "mask": "9606",
      "name": "Link Money Checking",
      "official_name": "Link Money Gold Checking",
      "subtype": "checking",
      "type": "depository"
    }
  ],
  "numbers": {
    "ach": [
      {
        "account": "9900009606",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "routing": "011401533",
        "wire_routing": "021000021"
      }
    ],
    "eft": [
      {
        "account": "111122223333",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "institution": "021",
        "branch": "01140"
      }
    ],
    "international": [
      {
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "bic": "NWBKGB21",
        "iban": "GB29NWBK60161331926819"
      }
    ],
    "bacs": [
      {
        "account": "31926819",
        "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
        "sort_code": "601613"
      }
    ]
  },
  "item": {
    "available_products": [
      "balance",
      "identity",
      "payment_initiation",
      "transactions"
    ],
    "billed_products": [
      "assets",
      "auth"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_117650",
    "item_id": "DWVAAPWq4RHGlEaNyGKRTAnPLaEmo8Cvq7na6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "request_id": "m8MDnv9okwxFNBV"
}

Liabilities

The liabilities endpoint collection offers a single operation to retrieve liabilities. Liabilities are a specific type of account in LinkMoney's Plaid collection. To link Investments see the collection documentation. For any other type of account, use the generic Accounts & Transactions endpoints.

Retrieve Liabilities Data.

Endpoint: POST /liabilities/get

Retrieve various details about an Item with loan or credit accounts.

The types of information returned by Liabilities can include balances and due dates, loan terms, and specific details such as the original loan amount and guarantor.

Parameters

In the Request Body

NameLocationDescription
Request Body
An optional object to filter the results of this call.

Options

NameTypeDescription
String[]
An array of account_ids to retrieve for the Item. An error will be returned if a provided account_id is not associated with the Item.

Example Request

curl -X POST /liabilities/get \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}" \
-d '{}'

Example Response

{
  "accounts": [
    {
      "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp",
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    {
      "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
      "balances": {
        "available": null,
        "current": 410,
        "iso_currency_code": "USD",
        "limit": 2000,
        "unofficial_currency_code": null
      },
      "mask": "3333",
      "name": "Plaid Credit Card",
      "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
      "subtype": "credit card",
      "type": "credit"
    },
    {
      "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
      "balances": {
        "available": null,
        "current": 65262,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "7777",
      "name": "Plaid Student Loan",
      "official_name": null,
      "subtype": "student",
      "type": "loan"
    },
    {
      "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
      "balances": {
        "available": null,
        "current": 56302.06,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null
      },
      "mask": "8888",
      "name": "Plaid Mortgage",
      "official_name": null,
      "subtype": "mortgage",
      "type": "loan"
    }
  ],
  "item": {
    "available_products": [
      "balance",
      "investments"
    ],
    "billed_products": [
      "assets",
      "auth",
      "identity",
      "liabilities",
      "transactions"
    ],
    "consent_expiration_time": null,
    "error": null,
    "institution_id": "ins_3",
    "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
    "update_type": "background",
    "webhook": "https://www.genericwebhookurl.com/webhook"
  },
  "liabilities": {
    "credit": [
      {
        "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
        "aprs": [
          {
            "apr_percentage": 15.24,
            "apr_type": "balance_transfer_apr",
            "balance_subject_to_apr": 1562.32,
            "interest_charge_amount": 130.22
          },
          {
            "apr_percentage": 27.95,
            "apr_type": "cash_apr",
            "balance_subject_to_apr": 56.22,
            "interest_charge_amount": 14.81
          },
          {
            "apr_percentage": 12.5,
            "apr_type": "purchase_apr",
            "balance_subject_to_apr": 157.01,
            "interest_charge_amount": 25.66
          },
          {
            "apr_percentage": 0,
            "apr_type": "special",
            "balance_subject_to_apr": 1000,
            "interest_charge_amount": 0
          }
        ],
        "is_overdue": false,
        "last_payment_amount": 168.25,
        "last_payment_date": "2019-05-22",
        "last_statement_issue_date": "2019-05-28",
        "minimum_payment_amount": 20,
        "next_payment_due_date": "2020-05-28"
      }
    ],
    "mortgage": [
      {
        "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
        "account_number": "3120194154",
        "current_late_fee": 25,
        "escrow_balance": 3141.54,
        "has_pmi": true,
        "has_prepayment_penalty": true,
        "interest_rate": {
          "percentage": 3.99,
          "type": "fixed"
        },
        "last_payment_amount": 3141.54,
        "last_payment_date": "2019-08-01",
        "loan_term": "30 year",
        "loan_type_description": "conventional",
        "maturity_date": "2045-07-31",
        "next_monthly_payment": 3141.54,
        "next_payment_due_date": "2019-11-15",
        "origination_date": "2015-08-01",
        "origination_principal_amount": 425000,
        "past_due_amount": 2304,
        "property_address": {
          "city": "Malakoff",
          "country": "US",
          "postal_code": "14236",
          "region": "NY",
          "street": "2992 Cameron Road"
        },
        "ytd_interest_paid": 12300.4,
        "ytd_principal_paid": 12340.5
      }
    ],
    "student": [
      {
        "account_id": "Pp1Vpkl9w8sajvK6oEEKtr7vZxBnGpf7LxxLE",
        "account_number": "4277075694",
        "disbursement_dates": [
          "2002-08-28"
        ],
        "expected_payoff_date": "2032-07-28",
        "guarantor": "DEPT OF ED",
        "interest_rate_percentage": 5.25,
        "is_overdue": false,
        "last_payment_amount": 138.05,
        "last_payment_date": "2019-04-22",
        "last_statement_issue_date": "2019-04-28",
        "loan_name": "Consolidation",
        "loan_status": {
          "end_date": "2032-07-28",
          "type": "repayment"
        },
        "minimum_payment_amount": 25,
        "next_payment_due_date": "2019-05-28",
        "origination_date": "2002-08-28",
        "origination_principal_amount": 25000,
        "outstanding_interest_amount": 6227.36,
        "payment_reference_number": "4277075694",
        "pslf_status": {
          "estimated_eligibility_date": "2021-01-01",
          "payments_made": 200,
          "payments_remaining": 160
        },
        "repayment_plan": {
          "description": "Standard Repayment",
          "type": "standard"
        },
        "sequence_number": "1",
        "servicer_address": {
          "city": "San Matias",
          "country": "US",
          "postal_code": "99415",
          "region": "CA",
          "street": "123 Relaxation Road"
        },
        "ytd_interest_paid": 280.55,
        "ytd_principal_paid": 271.65
      }
    ]
  },
  "request_id": "dTnnm60WgKGLnKL"
}

Assets

Asset endpoints allow you to create, delete, retrieve, and share Asset Reports with information about a user's assets and transactions.

Create an Asset Report

Endpoint: '/asset_report/create'

The create endpoint initiates the process of creating an Asset Report, which can then be retrieved by passing the asset_report_token return value to the /asset_report/get or /asset_report/pdf/get endpoints.

The Asset Report takes some time to be created and is not available immediately after calling create. When the Asset Report is ready to be retrieved using /asset_report/get or /asset_report/pdf/get, Plaid will fire a PRODUCT_READY webhook.

The create endpoint creates an Asset Report at a moment in time. Asset Reports are immutable. To get an updated Asset Report, use the refresh endpoint.

Request fields

FieldSub-FieldTypePurpose
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
string
An array of access tokens corresponding to the Items that will be included in the report. The assets product must have been initialized for the Items during link; the Assets product cannot be added after initialization. Min items: 1 Max items: 99
integer
The maximum integer number of days of history to include in the Asset Report. If using Fannie Mae Day 1 Certainty, days_requested must be at least 61 for new originations or at least 31 for refinancings. Maximum: 731 Minimum: 0
object
An optional object to filter /asset_report/create results. If provided, must be non-null. The optional user object is required for the report to be eligible for Fannie Mae's Day 1 Certainty program.
string
Client-generated identifier, which can be used by lenders to track loan applications.
string
URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready.
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
string
An identifier you determine and submit for the user.
first_name
string
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
string
The user's middle name.
last_name
string
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
string
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd"
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
string
The user's email address.

Example Request

const daysRequested = 60;
const options = {
  client_report_id: '123',
  webhook: 'https://www.example.com',
  user: {
    client_user_id: '7f57eb3d2a9j6480121fx361',
    first_name: 'Jane',
    middle_name: 'Leah',
    last_name: 'Doe',
    ssn: '123-45-6789',
    phone_number: '(555) 123-4567',
    email: 'jane.doe@example.com',
  },
};
const request: AssetReportCreateRequest = {
  access_tokens: [accessToken],
  days_requested,
  options,
};
// accessTokens is an array of Item access tokens.
// Note that the assets product must be enabled for all Items.
// All fields on the options object are optional.
try {
  const response = await plaidClient.assetReportCreate(request);
  const assetReportId = response.data.asset_report_id;
  const assetReportToken = response.data.asset_report_token;
} catch (error) {
  // handle error
}

Response Fields

FieldTypeDescription
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Example Response:

{
"asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
"asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
"request_id": "Iam3b"
}

Retrieve an Asset Report

Endpoint '/asset_report/get'

The get endpoint retrieves the Asset Report in JSON format. Before calling the get endpoint, you must first create the Asset Report using create (or filter an Asset Report using filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.

By default, an Asset Report includes transaction descriptions as returned by the bank, as opposed to parsed and categorized by Plaid. You can also receive cleaned and categorized transactions, as well as additional insights like merchant name or location information. We call this an Asset Report with Insights. An Asset Report with Insights provides transaction category, location, and merchant information in addition to the transaction strings provided in a standard Asset Report.

To retrieve an Asset Report with Insights, call the /asset_report/get endpoint with include_insights set to true.

Request Fields

FieldTypeDescription
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
boolean
true if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted. Default: false
const request: request = {
	asset_report_token: assetReportToken,
	include_insights: true,
};
try {
	const response = await plaidClient.assetReportGet(request);
	const assetReportId = response.data.asset_report_id;
} catch (error) {
	if (error.data.error_code == 'PRODUCT_NOT_READY') {
		// Asset report is not ready yet. Try again later
	} else {
		// handle error
	}
}

Response Fields

FieldSub-FieldTypeDescription
object
An object representing an Asset Report.
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
client_report_id
string
An identifier you determine and submit for the Asset Report.
date_generated
string
The date and time when the Asset Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z"). Format: date-time
days_requested
number
The duration of transaction history you requested.
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
stringnullable
An identifier you determine and submit for the user.
first_name
stringnullable
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
stringnullable
The user's middle name.
last_name
stringnullable
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
stringnullable
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd"
phone_number
stringnullable
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
stringnullable
the user's email address.
object
Data returned by Plaid about each of the Items included in the Asset Report.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
institution_name
string
The full financial institution name associated with the Item.
institution_id
string
The id of the financial institution associated with the Item.
date_last_updated
string
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format. Format: date-time
object
Data about each of the accounts open on the Item.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account. The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id. If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API. Like all Plaid identifiers, the account_id is case sensitive.
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
numbernullable
The amount of funds available to be withdrawn from the account, as determined by the financial institution. For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows. For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit. For investment-type accounts, the available balance is the total cash available to withdraw as presented by the institution. Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null. Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get. If current is null this field is guaranteed not to be null.
current
numbernullable
The total amount of funds in or owed by the account. For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder. For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest. For investment-type accounts, the current balance is the total value of assets as presented by the institution. Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get. When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.
limit
numbernullable
For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit-type accounts.
iso_currency_code
stringnullable
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
stringnullable
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
last_updated_datetime
stringnullable
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One). Format: date-time
mask
stringnullable
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself.
official_name
stringnullable
The official name of the account as given by the financial institution.
type
string
investment: Investment account credit: Credit card depository: Depository account loan: Loan account brokerage: An investment account. Used for /assets/ endpoints only; other endpoints use investment. other: Non-specified account type See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: investment, credit, depository, loan, brokerage, other
subtype
stringnullable
See the Account type schema for a full listing of account types and corresponding subtypes. Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only. pending_automatic_verification: The Item is pending automatic verification pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts. automatically_verified: The Item has successfully been automatically verified manually_verified: The Item has successfully been manually verified verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link. verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link. Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
days_available
number
The duration of transaction history available for this Item, typically defined as the time since the date of the earliest transaction in that account. Only returned by Assets endpoints.
object
Transaction history associated with the account. Only returned by Assets endpoints. Transaction history returned by endpoints such as /transactions/get or /investments/transactions/get will be returned in the top-level transactions field instead.
transaction_type
stringdeprecated
Please use the payment_channel field, transaction_type will be deprecated in the future. digital: transactions that took place online. place: transactions that were made at a physical location. special: transactions that relate to banks, e.g. fees or deposits. unresolved: transactions that do not fit into the other three types. Possible values: digital, place, special, unresolved
pending_transaction_id
stringnullable
The ID of a posted transaction's associated pending transaction, where applicable.
category_id
stringnullable
The ID of the category to which this transaction belongs. See Categories. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category
stringnullable
A hierarchical array of the categories to which this transaction belongs. See Categories. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
object
A representation of where a transaction took place.
address
stringnullable
The street address where the transaction occurred.
city
stringnullable
The city where the transaction occurred.
region
stringnullable
The region or state where the transaction occurred.
postal_code
stringnullable
The postal code where the transaction occurred.
country
stringnullable
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
numbernullable
The latitude where the transaction occurred.
lon
numbernullable
The longitude where the transaction occurred.
store_number
stringnullable
The merchant defined store number where the transaction occurred.
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. If the transactions object was returned by a Transactions endpoint such as /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
stringnullable
The transaction reference number supplied by the financial institution.
ppd_id
stringnullable
The ACH PPD ID for the payer.
payee
stringnullable
For transfers, the party that is receiving the transaction.
by_order_of
stringnullable
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
stringnullable
For transfers, the party that is paying the transaction.
payment_method
stringnullable
The type of transfer, e.g. 'ACH'.
payment_processor
stringnullable
The name of the payment processor.
reason
stringnullable
The payer-supplied description of the transfer.
account_owner
stringnullable
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
name
string
The merchant name or transaction description. If the transactions object was returned by a Transactions endpoint such as /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
original_description
stringnullable
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the account's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.
iso_currency_code
stringnullable
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
stringnullable
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the currency code schema for a full listing of supported iso_currency_codes.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). Format: date
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
date_transacted
stringnullable
The date on which the transaction took place, in ISO 8601 format.
object
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array.
names
string
A list of names associated with the account by the financial institution. These should always be the names of individuals, even for business accounts. If the name of a business is reported, please contact Plaid Support. In the case of a joint account, Plaid will make a best effort to report the names of all account holders. If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
object
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
The type of phone number. Possible values: home, work, office, mobile, mobile1, other
object
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
The type of email account as described by the financial institution. Possible values: primary, secondary, other
object
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
object
Data about the components comprising an address.
city
string
The full city name
region
stringnullable
The region or state Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
stringnullable
The postal code.
country
stringnullable
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
object
Calculated data about the historical balances on the account. Only returned by Assets endpoints.
date
string
The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD) Format: date
current
number
The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction. If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting.
iso_currency_code
stringnullable
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
stringnullable
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. See the currency code schema for a full listing of supported iso_currency_codes.
object
If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing.
warning_type
string
The warning type, which will always be ASSET_REPORT_WARNING.
warning_code
string
The warning code identifies a specific kind of warning. Currently, the only possible warning code is OWNERS_UNAVAILABLE, which indicates that account-owner information is not available. Possible values: OWNERS_UNAVAILABLE
object
An error object and associated item_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.
item_id
string
The item_id of the Item associated with this webhook, warning, or error.
objectnullable
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be null if no error has occurred.
error_type
string
A broad categorization of the error. Safe for programatic use. Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
stringnullable
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
requiest_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. causes will only be provided for the error_type ASSET_REPORT_ERROR.
status
numbernullable
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error.
suggested_action
string
Suggested steps for resolving the error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
  "report": {
    "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
    "client_report_id": "123abc",
    "date_generated": "2020-06-05T22:47:53Z",
    "days_requested": 3,
    "items": [
      {
        "accounts": [
          {
            "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
            "balances": {
              "available": 200,
              "current": 210,
              "iso_currency_code": "USD",
              "limit": null,
              "unofficial_currency_code": null
            },
            "days_available": 3,
            "historical_balances": [
              {
                "current": 210,
                "date": "2020-06-04",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2020-06-03",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2020-06-02",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "postal_code": "14236",
                      "region": "NY",
                      "street": "2992 Cameron Road"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "postal_code": "93405-2255",
                      "region": "CA",
                      "street": "2493 Leisure Lane"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "savings",
            "transactions": [],
            "type": "depository"
          },
          {
            "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
            "balances": {
              "available": null,
              "current": 56302.06,
              "iso_currency_code": "USD",
              "limit": null,
              "unofficial_currency_code": null
            },
            "days_available": 3,
            "historical_balances": [],
            "mask": "8888",
            "name": "Plaid Mortgage",
            "official_name": null,
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "postal_code": "14236",
                      "region": "NY",
                      "street": "2992 Cameron Road"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "postal_code": "93405-2255",
                      "region": "CA",
                      "street": "2493 Leisure Lane"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "mortgage",
            "transactions": [],
            "type": "loan"
          },
          {
            "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
            "balances": {
              "available": null,
              "current": 410,
              "iso_currency_code": "USD",
              "limit": null,
              "unofficial_currency_code": null
            },
            "days_available": 3,
            "historical_balances": [
              {
                "current": 410,
                "date": "2020-06-04",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 410,
                "date": "2020-06-03",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 410,
                "date": "2020-06-02",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "mask": "3333",
            "name": "Plaid Credit Card",
            "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "country": "US",
                      "postal_code": "14236",
                      "region": "NY",
                      "street": "2992 Cameron Road"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "country": "US",
                      "postal_code": "93405-2255",
                      "region": "CA",
                      "street": "2493 Leisure Lane"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile"
                  }
                ]
              }
            ],
            "ownership_type": null,
            "subtype": "credit card",
            "transactions": [],
            "type": "credit"
          }
        ],
        "date_last_updated": "2020-06-05T22:47:52Z",
        "institution_id": "ins_3",
        "institution_name": "Chase",
        "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
      }
    ],
    "user": {
      "client_user_id": "123456789",
      "email": "accountholder0@example.com",
      "first_name": "Alberta",
      "last_name": "Charleson",
      "middle_name": "Bobbeth",
      "phone_number": "111-222-3333",
      "ssn": "123-45-6789"
    }
  },
  "request_id": "eYupqX1mZkEuQRx",
  "warnings": []
}

Retrieve a PDF Asset Report

Endpoint: '/asset_report/pdf/get'

The '/asset_report/pdf/get' endpoint retrieves the Asset Report in PDF format. Before calling '/asset_report/pdf/get', you must first create the Asset Report using '/asset_report/create' (or filter an Asset Report using '/asset_report/filter') and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.

The response to '/asset_report/pdf/get' is the PDF binary data. The request_id

is returned in the Plaid-Request-ID header.

Request Fields

FieldTypeDescription
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
stringrequired
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.

Example Request

try {
  const request: AssetReportPDFGetRequest = {
    asset_report_token: assetReportToken,
  };
  const response = await plaidClient.assetReportPdfGet(request, {
    responseType: 'arraybuffer',
  });
  const pdf = response.buffer.toString('base64');
} catch (error) {
  // handle error
}

A PDF of the Asset Report will be returned.

Refresh an Asset Report

Endpoint: '/asset_report/refresh'

An Asset Report is an immutable snapshot of a user's assets. In order to "refresh" an Asset Report you created previously, you can use the '/asset_report/refresh' endpoint to create a new Asset Report based on the old one, but with the most recent data available.

The new Asset Report will contain the same Items as the original Report, as well as the same filters applied by any call to '/asset_report/filter'. By default, the new Asset Report will also use the same parameters you submitted with your original '/asset_report/create' request, but the original days_requested value and the values of any parameters in the options object can be overridden with new values. To change these arguments, simply supply new values for them in your request to '/asset_report/refresh'. Submit an empty string ("") for any previously-populated fields you would like set as empty.

Request Fields

FieldSub-FieldTypeDescription
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
stringrequired
The asset_report_token returned by the original call to /asset_report/create
number
The maximum number of days of history to include in the Asset Report. Must be an integer. If not specified, the value from the original call to /asset_report/create will be used. Minimum: 0 Maximum: 731
object
An optional object to filter /asset_report/refresh results. If provided, cannot be null. If not specified, the options from the original call to /asset_report/create will be used.
client_report
string
Client-generated identifier, which can be used by lenders to track loan applications.
webhook
string
URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready.
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
string
An identifier you determine and submit for the user.
first_name
string
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
string
The user's middle name.
last_name
string
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
string
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program. Format: "ddd-dd-dddd"
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
string
The user's email address.
const request: AssetReportRefreshRequest = {
  asset_report_token: assetReportToken,
  daysRequested: 60,
  options: {
    client_report_id: '123',
    webhook: 'https://www.example.com',
    user: {
      client_user_id: '7f57eb3d2a9j6480121fx361',
      first_name: 'Jane',
      middle_name: 'Leah',
      last_name: 'Doe',
      ssn: '123-45-6789',
      phone_number: '(555) 123-4567',
      email: 'jane.doe@example.com',
    },
  },
};
try {
  const response = await plaidClient.assetReportRefresh(request);
  const assetReportId = response.data.asset_report_id;
} catch (error) {
  // handle error
}

Response Fields

FieldTypeDescription
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq"
}

Filter Asset Report

Endpoint: '/asset_report/filter'

By default, an Asset Report will contain all of the accounts on a given Item. In some cases, you may not want the Asset Report to contain all accounts. For example, you might have the end user choose which accounts are relevant in Link using the Account Select view, which you can enable in the dashboard. Or, you might always exclude certain account types or subtypes, which you can identify by using the '/accounts/get' endpoint. To narrow an Asset Report to only a subset of accounts, use the '/asset_report/filter' endpoint.

To exclude certain Accounts from an Asset Report, first use the '/asset_report/create' endpoint to create the report, then send the asset_report_token along with a list of account_ids to exclude to the '/asset_report/filter' endpoint, to create a new Asset Report which contains only a subset of the original Asset Report's data.

Because Asset Reports are immutable, calling '/asset_report/filter' does not alter the original Asset Report in any way; rather, '/asset_report/filter' creates a new Asset Report with a new token and id. Asset Reports created via '/asset_report/filter' do not contain new Asset data, and are not billed.

Plaid will fire a PRODUCT_READY webhook once generation of the filtered Asset Report has completed.

Request Fields

FieldTypeDescription
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
stringrequired
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
stringrequired
The accounts to exclude from the Asset Report, identified by account_id.
const request: AssetReportFilterRequest = {
  asset_report_token: assetReportToken,
  account_ids_to_exclude: ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'],
};
try {
  const reponse = await plaidClient.assetReportFilter(request);
  const assetReportId = response.data.asset_report_id;
} catch (error) {
  // handle error
}

Response Fields

FieldTypeDescription
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
  "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
  "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
  "request_id": "qEg07"
}

Delete and Asset Report

Endpoint: '/asset_report/remove'

The '/item/remove' endpoint allows you to invalidate an access_token, meaning you will not be able to create new Asset Reports with it. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove them specifically.

The '/asset_report/remove' endpoint allows you to remove an Asset Report. Removing an Asset Report invalidates its asset_report_token, meaning you will no longer be able to use it to access Report data or create new Audit Copies. Removing an Asset Report does not affect the underlying Items, but does invalidate any audit_copy_tokens associated with the Asset Report.

Request Fields

FieldTypeDescription
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
const request: AssetReportRemoveRequest = {
  asset_report_token: assetReportToken,
};
try {
  const response = await plaidClient.assetReportRemove(request);
  const removed = response.data.removed;
} catch (error) {
  // handle error
}

Response Fields

FieldTypeDescription
boolean
true if the Asset Report was successfully removed.
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
  "removed": true,
  "request_id": "I6zHN"
}

Create an Asset Report Audit Copy

Endpoint: '/asset_report/audit_copy/create'

Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid can supply an Audit Copy directly to Fannie Mae on your behalf if you participate in the Day 1 Certainty™ program. An Audit Copy contains the same underlying data as the Asset Report.

To grant access to an Audit Copy, use the '/asset_report/audit_copy/create' endpoint to create an audit_copy_token and then pass that token to the third party who needs access. Each third party has its own auditor_id, for example 'fannie_mae'. You’ll need to create a separate Audit Copy for each third party to whom you want to grant access to the Report.

Request Fields

FieldTypeDescription
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
stringrequired
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
stringrequired
The auditor_id of the third party with whom you would like to share the Asset Report.
// The auditor ID corresponds to the third party with which you want to share
// the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
const request: AssetReportAuditCopyCreateRequest = {
  asset_report_token: createResponse.data.asset_report_token,
  auditor_id: 'fannie_mae',
};
try {
  const response = await plaidClient.assetReportAuditCopyCreate(request);
  const auditCopyToken = response.data.audit_copy_token;
} catch (error) {
  // handle error
}

Response Fields

FieldTypeDescription
string
A token that can be shared with a third party auditor to allow them to obtain access to the Asset Report. This token should be stored securely.
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
  "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
  "request_id": "Iam3b"
}

Remove Asset Report Audit Copy

Endpoint: '/asset_report/audit_copy/remove'

The /asset_report/audit_copy/remove endpoint allows you to remove an Audit Copy. Removing an Audit Copy invalidates the audit_copy_token associated with it, meaning both you and any third parties holding the token will no longer be able to use it to access Report data. Items associated with the Asset Report, the Asset Report itself and other Audit Copies of it are not affected and will remain accessible after removing the given Audit Copy.

Request Fields

FieldTypeDescription
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
stringrequired
The audit_copy_token granting access to the Audit Copy you would like to revoke.
// auditCopyToken is the token from the createAuditCopy response.
const request: AssetReportAuditCopyRemoveRequest = {
  audit_copy_token: auditCopyToken,
};
try {
  const response = await plaidClient.assetReportAuditCopyRemove(request);
  const removed = response.data.removed;
} catch (error) {
  // handle error
}

Response Fields

FieldTypeDescription
boolean
true if the Audit Copy was successfully removed.
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
{
  "removed": true,
  "request_id": "m8MDnv9okwxFNBV"
}

Endpoints

EndpointDescription
Returns information about the status of an item.
Removes a specific Item.
Updates the webhooks associated with an item.
Gets a list of institutions available through Link Money API.
Gets an institution with a particular ID in the Link Money API.
Search for a particular institution.
Get all the accounts associated with a single item.
Get all the transactions associated with a single item.
Request a refresh on transactions associated with a single item.
Get all the categories supported by the Link Money API.
Get the balances of accounts associated with a single item.
Get a list of user-authorized stock position data for investment-type accounts.
Retrieve user-authorized transaction data for investment accounts.
Retrieve various details about an Item with loan or credit accounts.

Endpoint Collections

NameDescription
Plaid endpoints are for developers who have been using Plaid as an aggregator. Developers can find near clones of the Plaid routes they were previously using.
MX endpoints are for developers who have been using MX as an aggregator. Developers can find near clones of the MX routes they were previously using.
Yodlee endpoints are for developers who have been using Yodlee as an aggregator. Developers can find near clones of the Yodlee routes they were previously using.
Developer configurations are how Link Money stores details about particular developer accounts, including their data type and webhook preferences.
Link Money API provides more than the traditional aggregation function suite. Any additional custom features may live here.

Plaid Webhooks

Link Money API uses Webhooks to send updates to developers that lets developer applications know about data changes for new transactions, account balance updates, new account connections, and anything else worth sending a real-time update. This functionality also lets developers who use it skip having to pull data from the Link Money API on regular intervals to keep their applications abreast of the freshest user data.

Different aggregators have different webhook methodologies, schemas, and approaches. Link Money API offers webhooks in a variety of formats to make migrating from another aggregator's webhook system.

Plaid offers developers a robust series of events that trigger webhooks for a variety of reasons. Developers use these webhooks to keep their user data current with their user's accounts. Plaid's webhooks follow a specific model. Developers must write code that adheres to this model, and changing webhook reception code can be tedious and painstaking. Link Money therefore offers webhook subscriptions for Plaid-specific webhook integrations so that developers don't need to change their backend code in any way.

💡
Prerequisite: This documentation assumes that the developer has already followed the Registering for Webhooks overview and understands how to create a developer configuration with Link Money.

Item Webhooks

Item webhooks communicate changes or errors with Items. Often, errors with item webhooks describe account linking problems that the end user must take action to remediate.

Item webhooks also communicate changes with particular items that are not erroneous, such as intentional unlinking of accounts.

An Item Has Encountered An Error.

The developer can subscribe to receive a notification whenever there is a problem with an Item that the developer has access to.

Subscribing

Receiving

Parameters

Webhook

FieldTypeDescriptionRequired
string
Indicates the type of the webhook. For this webhook, it will always be ITEM.
string
Indicates the code of the webhook. For this webhook, it will always be ERROR.
string
The identifier for which item the error refers to.
Error
An error object describing the particular problem that has occurred (see the
Plaid Error Reference
) for in-depth documentation of this object.

Example Webhook

{
  "webhook_type": "ITEM",
  "webhook_code": "ERROR",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": {
    "display_message": null,
    "error_code": "ITEM_LOGIN_REQUIRED",
    "error_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",
    "error_type": "ITEM_ERROR",
    "status": 400
  }
}

An Item Is Approaching Expiration

Some institutions require users coming from the LinkMoney experience to periodically resupply their credentials to keep an account connection active. LinkMoney supplies developers with advance warning that such an expiration is approaching.

Subscribing

Receiving

Parameters

Webhook

NameTagsDescription
string
Describes the type of webhook that is being sent. In this case, it will always be ITEM.
string
Describes the code of the webhook that is being sent. In this case, it will always be PENDING_EXPIRATION
string
The identifier for which item the error refers to.
string
The date and time at which the Item's access will expire, in ISO 8601 format.

Example Webhook

{
  "webhook_type": "ITEM",
  "webhook_code": "PENDING_EXPIRATION",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "consent_expiration_time": "2020-01-15T13:25:17.766Z"
}

A User Has Revoked Permission to Access an Item.

End users of LinkMoney have the right and the ability to unlink their accounts from the LinkMoneyAPI. For developer experience, LinkMoney lets developers know when one of their subscribed user's items will no longer be linked.

Subscribing

Receiving

Parameters

Webhook

NameTagsDescription
string
Describes the type of webhook that is being sent. In this case, it will always be ITEM.
string
Describes the code of the webhook that is being sent. In this case, it will always be USER_PERMISSION_REVOKED.
string
The identifier for which item the error refers to.
Error
An Error item, as described in the
Plaid Error Reference
. In this case, the error will always have a code of
USER_PERMISSION_REVOKED
.

Example Webhook

{
  "webhook_type": "ITEM",
  "webhook_code": "USER_PERMISSION_REVOKED",
  "error": {
    "error_code": "USER_PERMISSION_REVOKED",
    "error_message": "the holder of this account has revoked their permission for your application to access it",
    "error_type": "ITEM_ERROR",
    "status": 400
  },
  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ"
}

The Item Webhook Configuration has been updated.

Whenever the developer changes their configuration to select new options or a new webhook URL, LinkMoney will trigger a webhook to notify their server at the newly-configured webhook URL of the update.

Subscribing

Receiving

Parameters

Webhook

NameTagsDescription
string
Describes the type of webhook that is being sent. In this case, it will always be ITEM.
string
Describes the code of the webhook that is being sent. In this case, it will always be WEBHOOK_UPDATE_ACKNOWLEDGED.
string
The identifier for which item the error refers to.
Error
An Error item, as described in the
Plaid Error Reference
. Occurs if something has gone wrong, otherwise this field will be null.
string
The new webhook URL.

Example Webhook

{
  "webhook_type": "ITEM",
  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_webhook_url": "https://plaid.com/example/webhook"
}

Transaction Webhooks

Transaction webhooks communicate changes in the transaction history for a particular item. This can include the removal of transactions, update to transactions, and new transactions associated with the account.

An Account Was Linked and Initial Transactions Are Available.

After an item is linked for the first time, a large amount of new transaction data for the last 30 days is retrieved for the newly-linked Item. This webhook lets developers know that the new data is now retrievable in the API.

Subscribing

Receiving

Parameters

Webhook

NameTagsDescription
string
Describes the type of webhook that is being sent. In this case, it will always be TRANSACTIONS.
string
Describes the code of the webhook that is being sent. In this case, it will always be INITIAL_UPDATE.
string
The identifier for which item the error refers to.
Error
Unless the initial update encountered an error, this field will be null. Otherwise, it will be an error as described by the
Plaid Error Reference
.
number
The number of new, unfetched transactions available.

Example Webhook

{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "INITIAL_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 19
}

Historical Transactions are Available.

After a developer asks for a large number of historical transactions, a webhook for the item the request was made on will fire, notifying the developer that the transactions are now available

Subscribing

Receiving

Parameters

Webhook

NameTagsDescription
string
Describes the type of webhook that is being sent. In this case, it will always be TRANSACTIONS.
string
Describes the code of the webhook that is being sent. In this case, it will always be HISTORICAL_UPDATE.
string
The identifier for which item the error refers to.
Error
Unless the operation encountered an error, this field will be null. Otherwise, it will be an error as described by the
Plaid Error Reference
.
number
The number of new, unfetched transactions available.

Example Webhook

{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "HISTORICAL_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 231
}

New Transactions are Available for an Item.

Several times a day, new transactions will become available for an item that a consumer spends regularly on. When this occurs, a new transactions webhook triggers.

Subscribing

Receiving

Parameters

Copy of Webhook

NameTagsDescription
string
Describes the type of webhook that is being sent. In this case, it will always be TRANSACTIONS.
string
Describes the code of the webhook that is being sent. In this case, it will always be DEFAULT_UPDATE.
string
The identifier for which item the error refers to.
Error
Unless the operation encountered an error, this field will be null. Otherwise, it will be an error as described by the
Plaid Error Reference
.
number
The number of new, unfetched transactions available.

Example Webhook

{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 3
}

Transactions have been Removed from an Item.

Sometimes transactions associated with an item are erroneous. If an institution subsequently deletes the transactions, LinkMoneyAPI fires a transaction removal webhook to the developer.

Subscribing

Receiving

Parameters

Copy of Webhook

NameTagsDescription
string
Describes the type of webhook that is being sent. In this case, it will always be ITEM.
string
Describes the code of the webhook that is being sent. In this case, it will always be TRANSACTIONS_REMOVED.
string
The identifier for which item the error refers to.
string[]
A list of the transaction_ids corresponding to the removed transactions.
Error
Unless the operation encountered an error, this field will be null. Otherwise, it will be an error as described by the
Plaid Error Reference
.

Example Webhook

Investment Webhooks

Investment webhooks communicate changes in investment-type accounts. For changes in ordinary accounts, see Item Webhooks. For changes in liability-type accounts, see Liability Webhooks.

Updates to an Investment Account's Holdings

Whenever holdings are added to or updated in an investment account, LinkMoney API triggers a webhook to notify authorized developers of the change.

Subscribe

Receive

Parameters

Webhook

FieldTypeDescription
string
The type of this webhook. In this case, the value will always be HOLDINGS.
string
The code for this webhook. In this case, the value will always be DEFAULT_UPDATE.
string
The ID of the Item this update is for.
Error
This field will be null if no error was encountered. If an error did occur, the error object is as described by the
Plaid Error Reference
.
number
The number of new holdings reported since the last time this webhook was fired.
number
The number of updated holdings reported since the last time this webhook was fired.

Example Webhook

{
  "webhook_type": "HOLDINGS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_holdings": 19,
  "updated_holdings": 0
}

New Transactions in an Investment Account.

Whenever new transactions are detected on an investment account, or whenever transactions are cancelled on an investment account, LinkMoneyAPI fires a webhook to notify authorized developers of the change.

Subscribe

Receive

Parameters

Webhook

FieldTypeDescription
string
The type of this webhook. In this case, the value will always be INVESTMENTS_TRANSACTIONS.
string
The code for this webhook. In this case, the value will always be DEFAULT_UPDATE.
string
The ID of the Item this update is for.
Error
This field will be null if no error was encountered. If an error did occur, the error object is as described by the
Plaid Error Reference
.
number
The number of new transactions reported since the last time this webhook was fired.
number
The number of canceled transactions reported since the last time this webhook was fired.

Example Webhook

{
  "webhook_type": "INVESTMENTS_TRANSACTIONS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_investments_transactions": 16,
  "canceled_investments_transactions": 0
}

Liability Webhooks

Liability webhooks communicate changes in liability-type accounts. For changes in ordinary accounts, see Item Webhooks. For changes in investment-type accounts, see Investment Webhooks.

Updates to an Liability Account's Holdings

Whenever new or updated liabilities are detected on a liabilities Item, LinkMoneyAPI triggers a webhook to notify authorized developers of the change.

Subscribe

Receive

Parameters

Webhook

FieldTypeDescription
string
The type of this webhook. In this case, the value will always be LIABILITIES.
string
The code for this webhook. In this case, the value will always be DEFAULT_UPDATE.
string
The ID of the Item this update is for.
Error
This field will be null if no error was encountered. If an error did occur, the error object is as described by the
Plaid Error Reference
.
string[]
An array of account_ids for accounts that contain new liabilities.
Object
An object with keys of account_ids that are mapped to their respective liabilities field that changed. See the example webhook for the conventional format.

Example Webhook

{
  "webhook_type": "LIABILITIES",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "account_ids_with_new_liabilities": [
    "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58",
    "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
  ],
  "account_ids_with_updated_liabilities": {
    "XMBvvyMGQ1UoLbKByoMqH3nXMj84ALSdE5B58": [
      "past_amount_due"
    ]
  }
}

Auth Webhooks

Auth webhooks communicate changes of verification status with Items. Attempting to retrieve an Item before micro deposit verification has succeeded will result in a response code of 400 and a Plaid error code of PRODUCT_NOT_READY.

Automatically Verified

Sent when an item has been successfully verified via automated micro deposits

Parameters

NameTypeDescription
String
Describes the type of webhook that is being sent. In this case, it will always be AUTH.
String
Describes the code of the webhook that is being sent. In this case, it will always be AUTOMATICALLY_VERIFIED.
String
The account_id of the account associated with the webhook
String
The item_id of the Item associated with this webhook, warning, or error

Example Webhook

{
  "webhook_type": "AUTH",
  "webhook_code": "AUTOMATICALLY_VERIFIED",
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK"
}

Verification Expired

Sent when an item has not been verified via automated micro deposits after seven days from when the micro deposits were made.

Parameters

NameTypeDescription
String
Describes the type of webhook that is being sent. In this case, it will always be AUTH.
String
Describes the code of the webhook that is being sent. In this case, it will always be VERIFICATION_EXPIRED.
String
The account_id of the account associated with the webhook
String
The item_id of the Item associated with this webhook, warning, or error

Example Webhook

{
  "webhook_type": "AUTH",
  "webhook_code": "VERIFICATION_EXPIRED",
  "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
  "account_id": "BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp"
}

Verification

Webhooks can be observed to come from LinkMoney web and IP addresses, but sometimes this is not enough to to verify that the webhook's payload is secure. To work around this, LinkMoney uses a Webhook-Verification header.

Note that the verification step is optional; LinkMoney webhooks can be used without the verification step.

ℹ️
LinkMoney does not recommend building authentication yourself. For this walkthrough, we are using the express-jwt package provided and maintained by Auth0.

Walkthrough

1. Extract the Webhook Verification Header.

const jwt = require("express-jwt");

const { headers } = request;
const verificationHeader = request['Webhook-Verification'];
// yields JWT
const JWT = jwt.decode(verificationHeader);

2. Validate the Decoded JWT (header) fields.

{
  "alg": "ES256",
  "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
  "typ": "JWT"
}
  • If the alg field is not ES256, reject the webhook.
  • If any of the above fields are missing, reject the webhook.

3. Use the kid field to request a webhook verification key.

const { kid } = JWT; // see step one for getting JWT
const response = await request("/webhook__verification_key", {
	method: "POST",
	headers: {
		"content-type": "application/json",
	},
	body: {
		"client_id": {MY_CLIENT_ID},
		"client_secret": {MY_CLIENT_SECRET),
		"key_id": kid, // add the kid here. 
	},
});

if (response.ok) {
	const data = await response.json(); 
	const { key } = data; 
	return key;
} else {
	// error 
}

This call will yield a JSON payload containing a single property, key. This key is a JWK.

{
  "key": {
    "alg": "ES256",
    "created_at": 1560466150,
    "crv": "P-256",
    "expired_at": null,
    "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
    "kty": "EC",
    "use": "sig",
    "x": "hKXLGIjWvCBv-cP5euCTxl8g9GLG9zHo_3pO5NN1DwQ",
    "y": "shhexqPB7YffGn6fR6h2UhTSuCtPmfzQJ6ENVIoO4Ys"
  },
  "request_id": "RZ6Omi1bzzwDaLo"
}

If the request does not return a key, reject the webhook.

4. Use the JWK to validate the webhook signature.

const client = new JwksClient(options)
const key; // see above for deriving the JWK
const jwtCheck = expressJwt({
	secret: key,
	// audience
	// issuer
	algorithms: ["ES256"],
});

module.exports = jwtCheck;

If the call's signature is invalid, it will be rejected by the middleware.

5. Call the JWT Check as Middleware.

app.post("/my-api/webhook", jwtCheck, // my middlewares); 

Full Example

//This example uses jose v2, not the latest version
const compare = require('secure-compare');
const jwt_decode = require('jwt-decode');
const JWT = require('jose');
const sha256 = require('js-sha256');

// Cache for webhook validation keys.
const KEY_CACHE = new Map();

const verify = async (body, headers) => {
  const signedJwt = JSON.parse(headers)['webhook-verification'];
  const decodedToken = jwt_decode(signedJwt);
  const decodedTokenHeader = jwt_decode(signedJwt, { header: true });
  const currentKeyID = decodedTokenHeader.kid;

  //If key not in cache, update the key cache
  if (!KEY_CACHE.has(currentKeyID)) {
    const keyIDsToUpdate = [];
    KEY_CACHE.forEach((keyID, key) => {
      if (key.expired_at == null) {
        keyIDsToUpdate.push(keyID);
      }
    });

    keyIDsToUpdate.push(currentKeyID);

    for (keyID of keyIDsToUpdate) {

			UPDATE WITH REQUEST !!!!!

      const verificationKeyResponse = await plaidClient
        .getWebhookVerificationKey(keyID)
        .catch((err) => {
          // decide how you want to handle unexpected API errors,
          // e.g. retry later
          return false;
        });
      const key = verificationKeyResponse.key;
      KEY_CACHE.set(keyID, key);
    }
  }

  // If the key ID is not in the cache, the key ID may be invalid.
  if (!KEY_CACHE.has(currentKeyID)) {
    return false;
  }

  // Fetch the current key from the cache.
  const key = KEY_CACHE.get(currentKeyID);

  // Reject expired keys.
  if (key.expired_at != null) {
    return false;
  }

  // Validate the signature and iat
  try {
    JWT.verify(signedJwt, key, { maxTokenAge: '5 min' });
  } catch (error) {
    return false;
  }

  // Compare hashes
  const bodyHash = sha256(body);
  const claimedBodyHash = decodedToken.request_body_sha256;
  return compare(bodyHash, claimedBodyHash);
};

Types of Plaid Webhooks

NameDescription
Item Webhooks communicate changes to Items.
Transaction Webhooks communicate changes to transaction data, including Initial Transaction Drops, New Transactions, Deleted Transactions, and Historical Data Pulls.
Investment Webhooks communicate changes in transaction data for investment-type accounts.
Liability Webhooks communicate changes in transaction data for loan-type accounts.

Plaid Schemas

Accounts
type: object
properties:
  account_id:
    type: string
    description: Plaid's unique identifier for the account. 
    example: 
  balances: 
    type: object
    description: A set of fields describing the balance for an account.
    properties:
      available: 
        type: number
        description: The amount of funds available to be withdrawn from the account.
        example: 
      current: 
        type: number 
        description: The total amount of funds in or owed by the accounts.
        example:
      limit: 
        type: number
        description: For credit-type accounts, this represents the credit limit.
        example: 
      iso_currency_code:
        type: string
        description: The ISO-4217 currency code of the balance.
        example: "USD"
      unofficial_currency_code: 
        type: string
        description: The unofficial currency code associated with the balance. 
        example:
  mask:
    type: string
    description: The last 2-4 alphanumeric characters of an account's official account number.
    example: "2345"
  name:
    type: string
    description: The name of the account, either assigned by the user or by the financial institution.
    example: "Joe's Checking"
  official_name: 
    type: string
    description: The official name of the account as given by the financial institution.
    example: "CHECKING"
  type: 
    type: string
    description: The variety of the account.
    examples:
      - credit
      - loan
      - investment
      - depository
      - brokerage
  subtype:
    type: string
    description: The subvariety of the account, if applicable.
    examples:
      - 401a
      - 401k
      - savings account
      - credit card
      - roth
      - mortgage
  verification_status: 
    type: string
    description: The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
    example: pending_automatic_verification
Calls to Action (FinSights)
type: object
properties:
  transaction_id:
    type: string
    description: "The Plaid issued transactionID for this particular transaction."
    example: "dfg74Fi3so8dRsw4378c"
    required: true
  account_id:
    type: string
    description: "The Plaid-issued accountID for the account this transaction was made under."
    example: "F034jf439fSg09432pjegior"
    required: true
  account_owner:
    type: string
    description: The nickname of the owner of the account associated with this transaction.
    example: "JACKRYAN"
  amount:
    type: number
    description: "The amount of the transaction."
    example: 25.50
    required: true
  authorized_date:
    type: string
    description: An ISO formatted data for the transaction if the transaction has posted.
    example: "2020-12-30"
  iso_currency_code:
    type: string
    description: "The official currency code for the transaction amount."
    example: USD
    required: true
  unofficial_currency_code:
    type: string
    description: The unofficial currency code for the transaction amount.
  category:
    type: array
    items:
      type: string
    description: An array of categories pertaining to this transaction.
    example:
      - Food and Beverage
      - Coffee Shops
  category_id:
    type: string
    description: A unique alphanumeric ID issued by Plaid referring to the ID of the main category.
  date:
    type: string
    description: "An ISO date for the original date on which the transaction took place."
    example: "2020-12-25"
    required: true
  location:
    type: object
    properties:
      address:
        type: string
        description: The street address where the transaction took place.
        example: "1234 South Street"
      city:
        type: string
        description: The city where the transaction took place.
        example: Lafayette
      lat:
        type: number
        description: The latitude where the transaction took place.
        example:
      lon:
        type: number
        description: The longitude where the transaction took place.
        example:
      store_number:
        type: number
        description: The number of the specific store if the transaction took place at a brick-and-mortar chain.
        example: 2243
      region:
        type: string
        description: The broad region where the transaction took place. In the US, this is usually the state.
        example: CO
      postal_code:
        type: string
        description: The postal code where the transaction took place.
        example: "80027"
      country:
        type: string
        description: The country where the transaction took place.
        example: USA
  merchant_name:
    type: string
    description: The Plaid-issued name of the merchant where the transaction is from.
    example: Otis Coffee Company
  name:
    type: string
    description: "The main Plaid-issued name of the merchant where the transaction is from"
    example: Otis Coffee Company
    required: true
  payment_channel:
    type: string
    description: The payment channel for the transaction.
    example: Online
  pending:
    type: boolean
    description: "Denotes whether the transaction is pending or posted."
    example: false
    required: true
  pending_transaction_id:
    type: string
    description: "The Plaid-issued unique alphanumeric ID for the associated pending transaction record if this transaction has posted."
  transaction_type:
    type: string
    description: Shows the type of the transaction.
    example: debit
  transaction_code:
    type: string
    description: The code of the transaction.
    example: "yes"
  uid:
    type: string
    description: "The unique alphanumeric ID of the user within either the client's system, or the unique user ID generated by Plaid."
    example: 1pfmZehrgenWog4kfn3pI4sd
    required: true
  insight_text:
    type: string
    description: A short, descriptive test field describing the advice or deal that a fingineer has discovered for this transaction.
    example: "sss"
  insight_ctaurl:
    type: string
    description: The call to action URL for the advice. Sends the end user to a web page for actionable information to follow the advice. 
  finsight_image:
    type: string 
    description: A url for a relevant image associated with the advice. Generally, this will be a logo for the merchant FinGoal recommends. 
  recommendation:
    type: string
    description: A short title for the Finsight. Generally this will be the name of the merchant that FinGoal recommends.
  amountFound:
    type: float
    description: The amount of "found money" the fingineer estimates this advice will save the end user if it is followed.
Transaction
type: object
properties:
  transaction_id:
    type: string
    description: "The Plaid issued transactionID for this particular transaction."
    example: "dfg74Fi3so8dRsw4378c"
    required: true
  account_id:
    type: string
    description: "The Plaid-issued accountID for the account this transaction was made under."
    example: "F034jf439fSg09432pjegior"
    required: true
  account_owner:
    type: string
    description: The nickname of the owner of the account associated with this transaction.
    example: "JACKRYAN"
  amount:
    type: number
    description: "The amount of the transaction."
    example: 25.50
    required: true
  authorized_date:
    type: string
    description: An ISO formatted data for the transaction if the transaction has posted.
    example: "2020-12-30"
  iso_currency_code:
    type: string
    description: "The official currency code for the transaction amount."
    example: USD
    required: true
  unofficial_currency_code:
    type: string
    description: The unofficial currency code for the transaction amount.
  category:
    type: array
    items:
      type: string
    description: An array of categories pertaining to this transaction.
    example:
      - Food and Beverage
      - Coffee Shops
  category_id:
    type: string
    description: A unique alphanumeric ID issued by Plaid referring to the ID of the main category.
  date:
    type: string
    description: "An ISO date for the original date on which the transaction took place."
    example: "2020-12-25"
    required: true
  location:
    type: object
    properties:
      address:
        type: string
        description: The street address where the transaction took place.
        example: "1234 South Street"
      city:
        type: string
        description: The city where the transaction took place.
        example: Lafayette
      lat:
        type: number
        description: The latitude where the transaction took place.
        example:
      lon:
        type: number
        description: The longitude where the transaction took place.
        example:
      store_number:
        type: number
        description: The number of the specific store if the transaction took place at a brick-and-mortar chain.
        example: 2243
      region:
        type: string
        description: The broad region where the transaction took place. In the US, this is usually the state.
        example: CO
      postal_code:
        type: string
        description: The postal code where the transaction took place.
        example: "80027"
      country:
        type: string
        description: The country where the transaction took place.
        example: USA
  merchant_name:
    type: string
    description: The Plaid-issued name of the merchant where the transaction is from.
    example: Otis Coffee Company
  name:
    type: string
    description: "The main Plaid-issued name of the merchant where the transaction is from"
    example: Otis Coffee Company
    required: true
  payment_channel:
    type: string
    description: The payment channel for the transaction.
    example: Online
  pending:
    type: boolean
    description: "Denotes whether the transaction is pending or posted."
    example: false
    required: true
  pending_transaction_id:
    type: string
    description: "The Plaid-issued unique alphanumeric ID for the associated pending transaction record if this transaction has posted."
  transaction_type:
    type: string
    description: Shows the type of the transaction.
    example: place
  transaction_code:
    type: string
    description: The code of the transaction.
    example: "purchase"
  uid:
    type: string
    description: "The unique alphanumeric ID of the user within either the client's system, or the unique user ID generated by Plaid."
    example: 1pfmZehrgenWog4kfn3pI4sd
    required: true
User
type: object
properties:
  city: 
    type: string
    description: The city where the user resides.
    example: Malakoff
  country: 
    type: string
    description: The country where the user resides.
    example: US
  postal_code:
    type: string
    description: The zip code where the user resides.
    example: "14326"
  region: 
    type: string
    description: The region (in the US, state) where the user resides.
    example: "NY"
  street:
    type: string
    description: The street address for the user.
    example: "2992 Cameron Road"
  emails:
    type: array
    description: An array of the emails associated with the account.
    example: 
      - totally.fake.email@notreal.com
  names:
    type: string
    description: The user's name.
    example: Cameron Howe
  phone_numbers:
    type: array
    description: An array of the user's phone numbers.
    example:
      - "1112223333"