# Investment Data
source: https://developer.mastercard.com/open-finance-us/documentation/usecases/investment-data/index.md
Investment accounts often represent a significant portion of a customer's assets. Mastercard Open Finance US enables you to access customer-permissioned investment account data --- including accounts, balances, holdings, and related activity --- using the same APIs you already use for other financial account types.
Investment data can help you create a more complete view of a customer's
finances. You can use it to:
* Present a more complete net worth view
* Build more meaningful financial wellness experiences
* Personalize onboarding, segmentation, and recommendations
* Support wealth and advisory experiences
* Reduce reliance on manual asset verification and document uploads
## How It Works {#how-it-works}
For investment data use cases, follow the same flow as for other account types. Eligible investment accounts are returned through the regular Account Aggregation and Transaction Data APIs with no need for any additional API calls.
After a customer consents to share their accounts, all account, holdings, and transaction data is retrieved using these APIs. The results can then be used in your financial apps to help customers understand their full financial position.
Use this flow to retrieve investment data with a customer's other account data:
* Generate a [Mastercard Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md). The Data Connect experience enables your customer to link eligible accounts and grant access to their financial data.
* If you need the most recent available data for your use case, call the appropriate [Refresh Customer Accounts endpoint](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md). Mastercard also refreshes active accounts during nightly batch aggregation.
* Call [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-full-details-afd-or-account-limited-aggregation-ala) to retrieve the customer's accounts. Use the `type` field to identify investment accounts.
* Call [Get All Customer Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#get-all-customer-transactions) to retrieve investment activity within a specified date range. Activity can include purchases, sales, dividends, and contributions.
This solution uses the following services:
#### Account Aggregation {#account-aggregation}
Retrieve account data, including available investment accounts and holdings.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md)
#### Transaction Data {#transaction-data}
Get investment activity, such as buys, sells, and dividends.
[Documentation →](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md)
Diagram usecase_investment
## Available Investment Data {#available-investment-data}
Depending on the institution and account type, investment accounts may return account-level data, holdings, and activity.
Investment account types include:
* Brokerage accounts
* Retirement accounts, such as individual retirement accounts (IRAs), rollover IRAs, and Roth IRAs
* Employer-sponsored accounts, such as 401(k), 403(b), 457, 401(a), Simplified Employee Pension (SEP) IRA, SIMPLE IRA, Thrift Savings Plan, and Employee Stock Purchase Plan accounts
* Specialty accounts, such as 529 plans, education savings accounts, Uniform Gifts to Minors Act (UGMA) accounts, Uniform Transfers to Minors Act (UTMA) accounts, and health savings accounts (HSAs)
Note: Availability of data varies by institution and account type.
## Account and Holdings Data {#account-and-holdings-data}
Investment accounts are returned through the same [Get Customer Accounts](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/index.md#account-full-details-afd-or-account-limited-aggregation-ala)
flow as other account types. In addition to standard fields such as `name`,
`type`, and `balance`, an investment account can include a `position` array.
Each object in the array represents a separate holding.
The following example shows an investment account object within a **Get
Customer Accounts** response:
```JSON
{
"accounts": [
{
"id": "123456789",
"name": "Individual Brokerage",
"balance": 25600.13,
"type": "brokerage",
"aggregationStatusCode": 0,
"detail": {
"margin": 0.00,
"marginAllowed": false,
"availableCashBalance": 9324.91000000,
"currentBalance": 25600.13000000,
"description": "Individual Brokerage"
},
"position": [
{
"securityId": "31617H102",
"securityIdType": "CUSIP",
"posType": "LONG",
"id": 1016486903,
"symbol": "SPAXX",
"currentPrice": 1.00000000,
"marketValue": 9324.91000000,
"units": 9324.91000000,
"type": "LONG",
"status": "A",
"securityType": "MUTUAL FUND",
"description": "FIDELITY GOVERNMENT MONEY MARKET"
},
{
"averageCost": 3088.00000000,
"securityId": "037833100",
"securityIdType": "CUSIP",
"posType": "LONG",
"symbol": "AAPL",
"securityName": "Apple Inc.",
"paidPrice": 123.52000000,
"currentPrice": 248.70000000,
"marketValue": 6217.50000000,
"holdType": "STOCK",
"units": 25.00000000,
"type": "LONG",
"status": "A",
"securityType": "STOCK",
"description": "Apple Inc."
},
{
"averageCost": 7734.40000000,
"securityId": "922908769",
"securityIdType": "CUSIP",
"posType": "LONG",
"symbol": "VTI",
"paidPrice": 193.36000000,
"currentPrice": 251.44000000,
"marketValue": 10057.72000000,
"units": 40.00000000,
"type": "LONG",
"status": "A",
"securityType": "ETF",
"securityName": "Vanguard Total Stock Market ETF",
"description": "Vanguard Total Stock Market ETF"
}
]
}
]
}
```
Using this data, you can present a customer's holdings in your app. For example, a holdings table might display:
| Symbol | Security Name | Units | Price | Market Value |
|--------|---------------------------------|-------|---------|--------------|
| AAPL | Apple Inc. | 25 | $185.12 | $4,628.00 |
| VTI | Vanguard Total Stock Market ETF | 40 | $251.44 | $10,057.60 |
You can also combine account balances and holdings into a portfolio summary, showing totals such as total investment value, number of linked accounts, top holdings, and the split between cash and invested balances.
## Investment Activity {#investment-activity}
Investment activity is returned through the standard [Get All Customer Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#get-all-customer-transactions) flow and can be displayed using familiar transaction patterns.
The following example shows how investment activity may appear in a **Get All Customer Transactions** response:
```JSON
{
"transactions": [
{
"id": 12345678901,
"amount": 1.76000000,
"uniqueTransactionId": "12345678901-09876543210",
"accountId": 1234567890,
"customerId": 1234567890,
"status": "active",
"description": "DIVIDEND RECEIVED VANGUARD BD INDEX FDS TOTAL BND MRKT (BND) (Cash)",
"type": "DIV",
"feeAmount": 0.00,
"symbol": "BND",
"unitQuantity": 0E-8,
"postedDate": 1785931200,
"transactionDate": 1785931200,
"createdDate": 1786061298,
"categorization": {
"normalizedPayeeName": "Vanguard",
"category": "Dividend & Cap Gains",
"bestRepresentation": "DIVIDEND RECEIVED VANGUARD BD INDEX FDS TOTAL BND MRKT (BND) (CASH)",
"country": "USA",
"entityStandardizationConfidenceScore": 100.0
},
"accruedInterestAmount": 0E-8,
"commissionAmount": 0E-8,
"unitPrice": 0E-8,
"securityType": "STOCK",
"ticker": "BND",
"securityId": "921937835",
"investmentTransactionType": "dividend"
},
{
"id": 123456789000,
"amount": -1.76000000,
"uniqueTransactionId": "12345678900-09876543200",
"accountId": 1234567890,
"customerId": 1234567890,
"status": "active",
"description": "PURCHASE INTO CORE ACCOUNT FIDELITY GOVERNMENT MONEY MARKET (SPAXX) MORNING TRADE (Cash)",
"feeAmount": 0.00,
"symbol": "SPAXX",
"unitQuantity": 1.76000000,
"postedDate": 1785931200,
"transactionDate": 1785931200,
"createdDate": 1786061298,
"categorization": {
"normalizedPayeeName": "Fidelity Investments",
"category": "Investments",
"bestRepresentation": "INTO CORE ACCOUNT FIDELITY GOVERNMENT MONEY MARKET (SPAXX) MORNING TRADE (CASH)",
"country": "USA",
"entityStandardizationConfidenceScore": 100.0
},
"accruedInterestAmount": 0E-8,
"commissionAmount": 0E-8,
"unitPrice": 1.00000000,
"securityType": "MUTUALFUND",
"ticker": "SPAXX",
"securityId": "31617H102",
"investmentTransactionType": "purchased"
},
{
"id": 123456788999,
"amount": -0.17000000,
"uniqueTransactionId": "12345678899-09876543199",
"accountId": 1234567890,
"customerId": 1234567890,
"status": "active",
"description": "FOREIGN TAX PAID NUTRIEN LTD COM NPV ISIN #CA67077M10... (NTR) (Cash)",
"feeAmount": 0.00,
"symbol": "NTR",
"unitQuantity": 0E-8,
"postedDate": 1784289600,
"transactionDate": 1784289600,
"createdDate": 1784414609,
"categorization": {
"normalizedPayeeName": "No Entity Found",
"category": "Taxes",
"bestRepresentation": "FOREIGN TAX PAID NUTRIEN LTD COM NPV ISIN #CA67077M10... (NTR) (CASH)",
"country": "USA",
"entityStandardizationConfidenceScore": 0.0
},
"accruedInterestAmount": 0E-8,
"commissionAmount": 0E-8,
"unitPrice": 0E-8,
"securityType": "STOCK",
"ticker": "NTR",
"securityId": "67077M108",
"investmentTransactionType": "tax"
},
{
"id": 123456788998,
"amount": -487.70000000,
"uniqueTransactionId": "123456788998-37831131590",
"accountId": 8023572288,
"customerId": 8016384990,
"status": "active",
"description": "SCHWAB FUNDAMENTAL INTERNATIONAL EQUITY ETF",
"memo": "DEBIT",
"type": "PURCHASED",
"feeAmount": 0.00,
"unitQuantity": 10.00000000,
"postedDate": 1772625600,
"transactionDate": 1772539200,
"createdDate": 1772630490,
"categorization": {
"normalizedPayeeName": "Charles Schwab",
"category": "Investments",
"bestRepresentation": "SCHWAB FUNDAMENTAL INTERNATIONAL EQUITY ETF",
"country": "USA",
"entityStandardizationConfidenceScore": 100.0
},
"commissionAmount": 0E-8,
"stateWithholding": 0.00,
"unitPrice": 48.77000000,
"withholding": "0.0",
"securityType": "STOCK",
"ticker": "FNDF",
"securityId": "808524755",
"investmentTransactionType": "purchased"
},
{
"id": 123456788997,
"amount": 0E-8,
"uniqueTransactionId": "12345678997-37676508487",
"accountId": 1234567890,
"customerId": 1234567890,
"status": "active",
"description": "CALL TRUIST FINL CORP $55 EXP 02/20/26",
"memo": "MEMO",
"type": "OPTIONEXPIRATION",
"feeAmount": 0.00,
"unitQuantity": 2.00000000,
"postedDate": 1771588800,
"transactionDate": 1771848000,
"createdDate": 1771869684,
"categorization": {
"normalizedPayeeName": "Truist Financial",
"category": "Financial",
"bestRepresentation": "CALL TRUIST FINL CORP $55 EXP 02 20 26 MEMO",
"country": "USA",
"entityStandardizationConfidenceScore": 100.0
},
"commissionAmount": 0E-8,
"stateWithholding": 0.00,
"unitPrice": 0E-8,
"withholding": "0.0",
"securityType": "OPTION",
"ticker": "TFC 260220C00055000",
"investmentTransactionType": "optionExpiration"
}
]
}
```
Investment transactions can include these additional fields:
* `unitQuantity` represents the number of shares or units in the transaction.
* `unitPrice` is the price per unit at the time of the transaction.
* `investmentTransactionType` identifies a normalized activity type, such as `purchased`, `sold`, or `dividend`. Mastercard derives this value from the `description` and `memo` fields.
Using this data, you can present investment activity in your app. For example:
| Date | Type | Security | Amount |
|-------------|----------|----------|-----------|
| 10 Apr 2026 | Purchase | AAPL | $1,850.00 |
| 05 Apr 2026 | Dividend | AAPL | $25.32 |
## What You Can Build {#what-you-can-build}
With investment data, you can power:
* Unified financial dashboards that combine banking, credit, and investment accounts
* Net worth and financial wellness tools that include long-term assets
* Retirement and long-term planning experiences
* Portfolio visibility and tracking
* Enhanced onboarding and segmentation based on investment account presence and balances
* Asset verification and profile enrichment that reduces manual input
## Next Steps {#next-steps}
### Quick Start Guide {#quick-start-guide}
Get started with using Mastercard Open Finance APIs in less than 30 minutes.
[Get Started →](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md)
### API Reference {#api-reference}
Find detailed explanation of all resources available through Mastercard Open Finance API.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md)
### Postman {#postman}
Run the Postman Collection to start using Open Finance API without the need to write any code.
[Learn More →](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/postman-collection/index.md)