Investments
API reference for Investments endpoints and webhooks
Endpoints | |
---|---|
/investments/holdings/get | Fetch investment holdings |
/investments/transactions/get | Fetch investment transactions |
In this section | |
---|---|
HOLDINGS: DEFAULT_UPDATE | New holdings available |
INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE | New transactions available |
Endpoints
/investments/holdings/get
Get Investment holdings
The /investments/holdings/get
endpoint allows developers to receive user-authorized stock position data for investment
-type accounts.
Request fields and example
client_id 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. | |
secret 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. | |
access_token requiredstring The access token associated with the Item data is being requested for. | |
options object An optional object to filter /investments/holdings/get results. If provided, must not be null .
|
1// Pull Holdings for an Item2const request: InvestmentsHoldingsGetRequest = {3 access_token: accessToken,4};5try {6 const response = await plaidClient.investmentsHoldingsGet(request);7 const holdings = response.data.holdings;8 const securities = response.data.securities;9} catch (error) {10 // handle error11}
Response fields and example
accounts [object] The accounts associated with the Item
| |||||||||||||||||||
holdings [object] The holdings belonging to investment accounts associated with the Item. Details of the securities in the holdings are provided in the securities field.
| |||||||||||||||||||
securities [object] Objects describing the securities held in the accounts associated with the Item.
| |||||||||||||||||||
item object Metadata about the Item.
| |||||||||||||||||||
request_id string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1{2 "accounts": [3 {4 "account_id": "5Bvpj4QknlhVWk7GygpwfVKdd133GoCxB814g",5 "balances": {6 "available": 43200,7 "current": 43200,8 "iso_currency_code": "USD",9 "limit": null,10 "unofficial_currency_code": null11 },12 "mask": "4444",13 "name": "Plaid Money Market",14 "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",15 "subtype": "money market",16 "type": "depository"17 },18 {19 "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",20 "balances": {21 "available": null,22 "current": 320.76,23 "iso_currency_code": "USD",24 "limit": null,25 "unofficial_currency_code": null26 },27 "mask": "5555",28 "name": "Plaid IRA",29 "official_name": null,30 "subtype": "ira",31 "type": "investment"32 },33 {34 "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",35 "balances": {36 "available": null,37 "current": 23631.9805,38 "iso_currency_code": "USD",39 "limit": null,40 "unofficial_currency_code": null41 },42 "mask": "6666",43 "name": "Plaid 401k",44 "official_name": null,45 "subtype": "401k",46 "type": "investment"47 }48 ],49 "holdings": [50 {51 "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",52 "cost_basis": 1,53 "institution_price": 1,54 "institution_price_as_of": "2021-04-13",55 "institution_value": 0.01,56 "iso_currency_code": "USD",57 "quantity": 0.01,58 "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",59 "unofficial_currency_code": null60 },61 {62 "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",63 "cost_basis": 1.5,64 "institution_price": 2.11,65 "institution_price_as_of": null,66 "institution_value": 2.11,67 "iso_currency_code": "USD",68 "quantity": 1,69 "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",70 "unofficial_currency_code": null71 },72 {73 "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",74 "cost_basis": 10,75 "institution_price": 10.42,76 "institution_price_as_of": null,77 "institution_value": 20.84,78 "iso_currency_code": "USD",79 "quantity": 2,80 "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",81 "unofficial_currency_code": null82 },83 {84 "account_id": "JqMLm4rJwpF6gMPJwBqdh9ZjjPvvpDcb7kDK1",85 "cost_basis": 0.01,86 "institution_price": 0.011,87 "institution_price_as_of": null,88 "institution_value": 110,89 "iso_currency_code": "USD",90 "quantity": 10000,91 "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",92 "unofficial_currency_code": null93 },94 {95 "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",96 "cost_basis": 23,97 "institution_price": 27,98 "institution_price_as_of": null,99 "institution_value": 636.309,100 "iso_currency_code": "USD",101 "quantity": 23.567,102 "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",103 "unofficial_currency_code": null104 },105 {106 "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",107 "cost_basis": 15,108 "institution_price": 13.73,109 "institution_price_as_of": null,110 "institution_value": 1373.6865,111 "iso_currency_code": "USD",112 "quantity": 100.05,113 "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",114 "unofficial_currency_code": null115 },116 {117 "account_id": "k67E4xKvMlhmleEa4pg9hlwGGNnnEeixPolGm",118 "cost_basis": 1,119 "institution_price": 1,120 "institution_price_as_of": null,121 "institution_value": 12345.67,122 "iso_currency_code": "USD",123 "quantity": 12345.67,124 "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",125 "unofficial_currency_code": null126 }127 ],128 "item": {129 "available_products": [130 "balance",131 "identity",132 "liabilities",133 "transactions"134 ],135 "billed_products": [136 "assets",137 "auth",138 "investments"139 ],140 "consent_expiration_time": null,141 "error": null,142 "institution_id": "ins_3",143 "item_id": "4z9LPae1nRHWy8pvg9jrsgbRP4ZNQvIdbLq7g",144 "update_type": "background",145 "webhook": "https://www.genericwebhookurl.com/webhook"146 },147 "request_id": "l68wb8zpS0hqmsJ",148 "securities": [149 {150 "close_price": 0.011,151 "close_price_as_of": "2021-04-13",152 "cusip": null,153 "institution_id": null,154 "institution_security_id": null,155 "is_cash_equivalent": false,156 "isin": null,157 "iso_currency_code": "USD",158 "name": "Nflx Feb 01'18 $355 Call",159 "proxy_security_id": null,160 "security_id": "8E4L9XLl6MudjEpwPAAgivmdZRdBPJuvMPlPb",161 "sedol": null,162 "ticker_symbol": "NFLX180201C00355000",163 "type": "derivative",164 "unofficial_currency_code": null165 },166 {167 "close_price": 27,168 "close_price_as_of": null,169 "cusip": "577130834",170 "institution_id": null,171 "institution_security_id": null,172 "is_cash_equivalent": false,173 "isin": "US5771308344",174 "iso_currency_code": "USD",175 "name": "Matthews Pacific Tiger Fund Insti Class",176 "proxy_security_id": null,177 "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",178 "sedol": null,179 "ticker_symbol": "MIPTX",180 "type": "mutual fund",181 "unofficial_currency_code": null182 },183 {184 "close_price": 2.11,185 "close_price_as_of": null,186 "cusip": "00448Q201",187 "institution_id": null,188 "institution_security_id": null,189 "is_cash_equivalent": false,190 "isin": "US00448Q2012",191 "iso_currency_code": "USD",192 "name": "Achillion Pharmaceuticals Inc.",193 "proxy_security_id": null,194 "security_id": "KDwjlXj1Rqt58dVvmzRguxJybmyQL8FgeWWAy",195 "sedol": null,196 "ticker_symbol": "ACHN",197 "type": "equity",198 "unofficial_currency_code": null199 },200 {201 "close_price": 10.42,202 "close_price_as_of": null,203 "cusip": "258620103",204 "institution_id": null,205 "institution_security_id": null,206 "is_cash_equivalent": false,207 "isin": "US2586201038",208 "iso_currency_code": "USD",209 "name": "DoubleLine Total Return Bond Fund",210 "proxy_security_id": null,211 "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",212 "sedol": null,213 "ticker_symbol": "DBLTX",214 "type": "mutual fund",215 "unofficial_currency_code": null216 },217 {218 "close_price": 1,219 "close_price_as_of": null,220 "cusip": null,221 "institution_id": null,222 "institution_security_id": null,223 "is_cash_equivalent": true,224 "isin": null,225 "iso_currency_code": "USD",226 "name": "U S Dollar",227 "proxy_security_id": null,228 "security_id": "d6ePmbPxgWCWmMVv66q9iPV94n91vMtov5Are",229 "sedol": null,230 "ticker_symbol": "USD",231 "type": "cash",232 "unofficial_currency_code": null233 },234 {235 "close_price": 13.73,236 "close_price_as_of": null,237 "cusip": null,238 "institution_id": "ins_3",239 "institution_security_id": "NHX105509",240 "is_cash_equivalent": false,241 "isin": null,242 "iso_currency_code": "USD",243 "name": "NH PORTFOLIO 1055 (FIDELITY INDEX)",244 "proxy_security_id": null,245 "security_id": "nnmo8doZ4lfKNEDe3mPJipLGkaGw3jfPrpxoN",246 "sedol": null,247 "ticker_symbol": "NHX105509",248 "type": "etf",249 "unofficial_currency_code": null250 }251 ]252}
Was this helpful?
/investments/transactions/get
Get investment transactions
The /investments/transactions/get
endpoint allows developers to retrieve up to 24 months of 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.
Due to the potentially large number of investment transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the total_investment_transactions
response body field to fetch all available investment transactions.
Request fields and example
client_id 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. | |||
secret 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. | |||
access_token requiredstring The access token associated with the Item data is being requested for. | |||
start_date requiredstring The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: date | |||
end_date requiredstring The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD. Format: date | |||
options object An optional object to filter /investments/transactions/get results. If provided, must be non-null .
|
1const request: InvestmentsTransactionsGetRequest = {2 access_token: accessToken,3 start_date: '2019-01-01',4 end_date: '2019-06-10',5};6try {7 const response = await plaidClient.investmentsTransactionsGet(request);8 const investmentTransactions = response.data.investment_transactions;9} catch (error) {10 // handle error11}
Response fields and example
item object Metadata about the Item.
| |||||||||||||||||||
accounts [object] The accounts for which transaction history is being fetched.
| |||||||||||||||||||
securities [object] All securities for which there is a corresponding transaction being fetched.
| |||||||||||||||||||
investment_transactions [object] The transactions being fetched
| |||||||||||||||||||
total_investment_transactions integer The total number of transactions available within the date range specified. If total_investment_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter.' | |||||||||||||||||||
request_id string A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. |
1{2 "accounts": [3 {4 "account_id": "5e66Dl6jNatx3nXPGwZ7UkJed4z6KBcZA4Rbe",5 "balances": {6 "available": 100,7 "current": 110,8 "iso_currency_code": "USD",9 "limit": null,10 "unofficial_currency_code": null11 },12 "mask": "0000",13 "name": "Plaid Checking",14 "official_name": "Plaid Gold Standard 0% Interest Checking",15 "subtype": "checking",16 "type": "depository"17 },18 {19 "account_id": "KqZZMoZmBWHJlz7yKaZjHZb78VNpaxfVa7e5z",20 "balances": {21 "available": null,22 "current": 320.76,23 "iso_currency_code": "USD",24 "limit": null,25 "unofficial_currency_code": null26 },27 "mask": "5555",28 "name": "Plaid IRA",29 "official_name": null,30 "subtype": "ira",31 "type": "investment"32 },33 {34 "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",35 "balances": {36 "available": null,37 "current": 23631.9805,38 "iso_currency_code": "USD",39 "limit": null,40 "unofficial_currency_code": null41 },42 "mask": "6666",43 "name": "Plaid 401k",44 "official_name": null,45 "subtype": "401k",46 "type": "investment"47 }48 ],49 "investment_transactions": [50 {51 "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",52 "amount": -8.72,53 "cancel_transaction_id": null,54 "date": "2020-05-29",55 "fees": 0,56 "investment_transaction_id": "oq99Pz97joHQem4BNjXECev1E4B6L6sRzwANW",57 "iso_currency_code": "USD",58 "name": "INCOME DIV DIVIDEND RECEIVED",59 "price": 0,60 "quantity": 0,61 "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",62 "subtype": "dividend",63 "type": "cash",64 "unofficial_currency_code": null65 },66 {67 "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",68 "amount": -1289.01,69 "cancel_transaction_id": null,70 "date": "2020-05-28",71 "fees": 7.99,72 "investment_transaction_id": "pK99jB9e7mtwjA435GpVuMvmWQKVbVFLWme57",73 "iso_currency_code": "USD",74 "name": "SELL Matthews Pacific Tiger Fund Insti Class",75 "price": 27.53,76 "quantity": -47.74104242992852,77 "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",78 "subtype": "sell",79 "type": "sell",80 "unofficial_currency_code": null81 },82 {83 "account_id": "rz99ex9ZQotvnjXdgQLEsR81e3ArPgulVWjGj",84 "amount": 7.7,85 "cancel_transaction_id": null,86 "date": "2020-05-27",87 "fees": 7.99,88 "investment_transaction_id": "LKoo1ko93wtreBwM7yQnuQ3P5DNKbKSPRzBNv",89 "iso_currency_code": "USD",90 "name": "BUY DoubleLine Total Return Bond Fund",91 "price": 10.42,92 "quantity": 0.7388014749727547,93 "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",94 "subtype": "buy",95 "type": "buy",96 "unofficial_currency_code": null97 }98 ],99 "item": {100 "available_products": [101 "assets",102 "balance",103 "identity",104 "transactions"105 ],106 "billed_products": [107 "auth",108 "investments"109 ],110 "consent_expiration_time": null,111 "error": null,112 "institution_id": "ins_12",113 "item_id": "8Mqq5rqQ7Pcxq9MGDv3JULZ6yzZDLMCwoxGDq",114 "update_type": "background",115 "webhook": "https://www.genericwebhookurl.com/webhook"116 },117 "request_id": "iv4q3ZlytOOthkv",118 "securities": [119 {120 "close_price": 27,121 "close_price_as_of": null,122 "cusip": "577130834",123 "institution_id": null,124 "institution_security_id": null,125 "is_cash_equivalent": false,126 "isin": "US5771308344",127 "iso_currency_code": "USD",128 "name": "Matthews Pacific Tiger Fund Insti Class",129 "proxy_security_id": null,130 "security_id": "JDdP7XPMklt5vwPmDN45t3KAoWAPmjtpaW7DP",131 "sedol": null,132 "ticker_symbol": "MIPTX",133 "type": "mutual fund",134 "unofficial_currency_code": null135 },136 {137 "close_price": 10.42,138 "close_price_as_of": null,139 "cusip": "258620103",140 "institution_id": null,141 "institution_security_id": null,142 "is_cash_equivalent": false,143 "isin": "US2586201038",144 "iso_currency_code": "USD",145 "name": "DoubleLine Total Return Bond Fund",146 "proxy_security_id": null,147 "security_id": "NDVQrXQoqzt5v3bAe8qRt4A7mK7wvZCLEBBJk",148 "sedol": null,149 "ticker_symbol": "DBLTX",150 "type": "mutual fund",151 "unofficial_currency_code": null152 },153 {154 "close_price": 34.73,155 "close_price_as_of": null,156 "cusip": "84470P109",157 "institution_id": null,158 "institution_security_id": null,159 "is_cash_equivalent": false,160 "isin": "US84470P1093",161 "iso_currency_code": "USD",162 "name": "Southside Bancshares Inc.",163 "proxy_security_id": null,164 "security_id": "eW4jmnjd6AtjxXVrjmj6SX1dNEdZp3Cy8RnRQ",165 "sedol": null,166 "ticker_symbol": "SBSI",167 "type": "equity",168 "unofficial_currency_code": null169 }170 ],171 "total_investment_transactions": 3172}
Was this helpful?
Webhooks
Updates are sent to indicate that new investment transactions are available.
HOLDINGS: DEFAULT_UPDATE
Fired when new or updated holdings have been detected on an investment account. The webhook typically fires once per day, after market close, in response to any newly added holdings or price changes to existing holdings.
webhook_type string HOLDINGS | |||||||||
webhook_code string DEFAULT_UPDATE | |||||||||
item_id string The item_id of the Item associated with this webhook, warning, or error | |||||||||
error object 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.
| |||||||||
new_holdings number The number of new holdings reported since the last time this webhook was fired. | |||||||||
updated_holdings number The number of updated holdings reported since the last time this webhook was fired. |
1{2 "webhook_type": "HOLDINGS",3 "webhook_code": "DEFAULT_UPDATE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "error": null,6 "new_holdings": 19,7 "updated_holdings": 08}
Was this helpful?
INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE
Fired when new or canceled transactions have been detected on an investment account.
webhook_type string INVESTMENTS_TRANSACTIONS | |||||||||
webhook_code string DEFAULT_UPDATE | |||||||||
item_id string The item_id of the Item associated with this webhook, warning, or error | |||||||||
error object 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.
| |||||||||
new_investments_transactions number The number of new transactions reported since the last time this webhook was fired. | |||||||||
canceled_investments_transactions number The number of canceled transactions reported since the last time this webhook was fired. |
1{2 "webhook_type": "INVESTMENTS_TRANSACTIONS",3 "webhook_code": "DEFAULT_UPDATE",4 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "error": null,6 "new_investments_transactions": 16,7 "canceled_investments_transactions": 08}