Introduction to Investments
View holdings and transactions from investment accounts
API Reference
View Investments requests, responses, and example code
View Investments APIQuickstart
Learn about Plaid's key concepts and run starter code
Get startedOverview
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.
Looking for Plaid's solution to automate ACATS transfers and avoid friction, failures, and delays due to manual data entry? See Investments Move instead.
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.
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 "market_identifier_code": "XNAS",18 "option_contract": null19}
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.
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": null11}
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.
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": null16}
Investments transactions initialization behavior
By default, if investments 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.
If you are adding Investments to an Item by calling /investments/transactions/get
after the Item was originally linked, instead of specifying the Investments product while calling /link/token/create
, you can optionally request asynchronous behavior by specifying async_update=true
. In this case, Investments will fire a HISTORICAL_UPDATE
webhook when data is ready to be fetched.
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.
You can also request an update on-demand via the /investments/refresh
endpoint, which is available as an add-on for Investments customers. To request access to this endpoint, submit a product access request or contact your Plaid account manager.
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.
When updating an Item with new Investments transactions data, it is recommended to call /investments/transactions/get
with only the date range that needs to be updated, rather than the maximum available date range, in order to reduce the amount of data that you must receive and process.
Testing Investments
Investments can be tested in Sandbox without any additional permissions.
Investments pricing
Investments is billed on a subscription model; Investments Refresh is billed on a per-request flat fee model. To view the exact pricing you may be eligible for, apply for Production access or contact Sales. For more details about pricing and billing models, see Plaid billing.
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.