Plaid logo
Docs
ALL DOCS

Investments

  • Introduction to Investments
  • Add Investments to your app
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Introduction to Investments

View holdings and transactions from investment accounts

Explore API

API Reference

View Investments requests, responses, and example code

View Investments API

Quickstart

Learn about Plaid's key concepts and run starter code

Get started

Overview

The Investments product allows you to obtain holding, security, and transactions data for investment-type accounts in financial institutions within the United States and Canada. This data can be used for personal financial management tools and wealth management analysis.

Securities and holdings

The /investments/holdings/get endpoint provides both security data and holding data. Security data represents information about a specific security, such as its name, ticker symbol, and price. Security data is not specific to a user's account; any user who held the same security at the same financial institution at the same time would have identical security data.

Copy
1{
2 "close_price": 10.42,
3 "close_price_as_of": null,
4 "cusip": "258620103",
5 "institution_id": null,
6 "institution_security_id": null,
7 "is_cash_equivalent": false,
8 "isin": "US2586201038",
9 "iso_currency_code": "USD",
10 "name": "DoubleLine Total Return Bond Fund",
11 "proxy_security_id": null,
12 "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
13 "sedol": null,
14 "ticker_symbol": "DBLTX",
15 "type": "mutual fund",
16 "unofficial_currency_code": null
17}

Holding data, by contrast, represents information about a user's specific ownership of that security, such as the number of shares owned and the cost basis. Each holding includes a security_id field that can be cross-referenced to a security for more detailed information about the security itself.

Copy
1{
2 "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",
3 "cost_basis": 10,
4 "institution_price": 10.42,
5 "institution_price_as_of": null,
6 "institution_value": 20.84,
7 "iso_currency_code": "USD",
8 "quantity": 2,
9 "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",
10 "unofficial_currency_code": null
11}

Transactions

The /investments/transactions/get endpoint provides up to 24 months of investment transactions data. The schema for investment transactions is not the same as for transactions data returned by the Transactions product, instead providing securities-specific information. Inflow, such as stock sales, is shown as a negative amount, and outflow, such as stock purchases, is positive. The /investments/transactions/get endpoint can only be used for investment-type accounts; for obtaining transaction history for other account types, use Transactions.

Copy
1{
2 "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",
3 "amount": -8.72,
4 "cancel_transaction_id": null,
5 "date": "2020-05-29",
6 "fees": 0,
7 "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",
8 "iso_currency_code": "USD",
9 "name": "INCOME DIV DIVIDEND RECEIVED",
10 "price": 0,
11 "quantity": 0,
12 "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",
13 "subtype": "dividend",
14 "type": "cash",
15 "unofficial_currency_code": null
16}

Investments updates and webhooks

Investments data is not static, since users' holdings will change as they trade and as market prices fluctuate. Plaid typically checks for updates to investment data overnight, after market hours. There are two webhooks that are used for informing you of changes to investment data. The DEFAULT_UPDATE webhook of type HOLDINGS fires when new holdings have been detected or the quantity or price of an existing holding has changed. The DEFAULT_UPDATE webhook of type INVESTMENTS_TRANSACTIONS fires when a new or canceled investment transaction has been detected.

Unlike Transactions, Investments does not have a webhook to indicate when initial transaction data has loaded. Instead, if transactions data is not ready when /investments/transactions/get is first called, Plaid will wait for the data. For this reason, calling /investments/transactions/get immediately after Link may take up to one to two minutes to return.

Testing Investments

Investments can be tested in Sandbox without any additional permissions. In order to test Investments against live Items in Development or Production, you will need to first request access by submitting a product access request Support ticket explaining your use case.

Next steps

To get started building with Investments, see Add Investments to your App.

If you're ready to launch to Production, see the Launch checklist.

Launch checklist

Recommended steps to take before launching in Production

Launch
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord