Documentation

Investments guide

Example response
Supported data elements

The Akoya Investments product combines basic end-user account information with balance data and extended investment details to provide your end-user with robust, in-depth insight into their investments.

Investments guide

The Investments product is supported by the /accounts endpoint which returns all accounts permissioned by the end-user. This means the response includes investment accounts + all other permissioned accounts. For instance, if your end-user has permissioned a checking account in addition to their investment account, the result will include investment and deposit account categories.

This endpoint returns all data available in both the Account info and Balances products plus all other available data for investment accounts including holdings, contributions, vesting, and more (listed below). To use this product, you must have the end-user’s consent and their associated ID token for permissioned data.

Results for investments are returned in JSON in FDX format. While this endpoint is needed to retrieve extended data for the investment account category, you may also use it for other account categories (annuity, deposit, insurance, line of credit, or loans). If used for account categories other than investment, you will receive the same data as with the balances product.

Example response

Data elements shown are not exhaustive

This is an example. See the chart below for a complete list of supported data elements.

JSON

{
  "accountId": "426444887",
  "accountType": "IRA",
  "accountNumberDisplay": "*****5071",
  "currency": {
    "currencyCode": "USD"
  },
  "description": "Rollover IRA",
  "fiAttributes": [],
  "nickname": "My IRA",
  "productName": "RolloverIRA Investment Acct",
  "status": "OPEN",
  "balanceType": "ASSET",
  "interestRateType": "FIXED",
  "interestRateAsOf": "2022-04-08T08:46:14",
  "lastActivityDate": "2022-04-08T08:46:14",
  "brokerId": "FID",
  "margin": false,
  "availableCashBalance": 69746.83,
  "balanceAsOf": "2022-04-08T08:46:14",
  "balanceList": [
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Minimumequitycall",
      "balanceType": "AMOUNT",
      "balanceValue": 0,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Regulatorynetworth",
      "balanceType": "AMOUNT",
      "balanceValue": 153015.21,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Usablenetworth",
      "balanceType": "AMOUNT",
      "balanceValue": 153015.21,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Cashcreditbalance",
      "balanceType": "AMOUNT",
      "balanceValue": 0,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Networthmarketvalue",
      "balanceType": "AMOUNT",
      "balanceValue": 153015.21,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Memoadjustment",
      "balanceType": "AMOUNT",
      "balanceValue": 0,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Cashmarginshortmarketvalue",
      "balanceType": "AMOUNT",
      "balanceValue": 69746.83,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Liquidationequitycall",
      "balanceType": "AMOUNT",
      "balanceValue": 0,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Totalsecuritiesmarketvalue",
      "balanceType": "AMOUNT",
      "balanceValue": 153015.21,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Corefundamount",
      "balanceType": "AMOUNT",
      "balanceValue": 83268.38,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Cashmoneymarket",
      "balanceType": "AMOUNT",
      "balanceValue": 83268.38,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Fullnetworth",
      "balanceType": "AMOUNT",
      "balanceValue": 153015.21,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Nettradedatecreditbalance",
      "balanceType": "AMOUNT",
      "balanceValue": 0,
      "currency": {
        "currencyCode": "USD"
      }
    },
    {
      "balanceDate": "2022-04-07T00:00:00",
      "balanceName": "Cashmarketvalue",
      "balanceType": "AMOUNT",
      "balanceValue": 69746.83,
      "currency": {
        "currencyCode": "USD"
      }
    }
  ],
  "currentValue": 153015.21,
  "marginBalance": 0,
  "holdings": [
    {
      "averageCost": false,
      "changeInPrice": 0,
      "currency": {
        "currencyCode": "USD"
      },
      "currentUnitPrice": 8.01,
      "currentUnitPriceDate": "2022-04-08T04:14:30",
      "description": "AB HIGH INCOME ADVISOR",
      "heldInAccount": "CASH",
      "holdingName": "AB HIGH INCOME ADVISOR",
      "holdingType": "MUTUALFUND",
      "marketValue": 49566.83,
      "positionType": "LONG",
      "securityId": "01859M408",
      "securityIdType": "CUSIP",
      "symbol": "AGDYX",
      "units": 6188.119
    },
    {
      "averageCost": false,
      "changeInPrice": 0,
      "currency": {
        "currencyCode": "USD"
      },
      "currentUnitPrice": 1,
      "currentUnitPriceDate": "2022-04-08T04:14:30",
      "description": "GOVERNMENT CASH RESERVES",
      "heldInAccount": "CASH",
      "holdingName": "GOVERNMENT CASH RESERVES",
      "holdingType": "MUTUALFUND",
      "marketValue": 83268.38,
      "positionType": "LONG",
      "securityId": "316067107",
      "securityIdType": "CUSIP",
      "symbol": "FDRXX",
      "units": 83268.38
    },
    {
      "averageCost": false,
      "changeInPrice": 0,
      "currency": {
        "currencyCode": "USD"
      },
      "currentUnitPrice": 201.8,
      "currentUnitPriceDate": "2022-04-08T04:14:30",
      "description": "FINANCIAL SERVICES GROUP COM USD5",
      "heldInAccount": "CASH",
      "holdingName": "FINANCIAL SERVICES GROUP COM USD5",
      "holdingType": "STOCK",
      "marketValue": 20180,
      "positionType": "LONG",
      "securityId": "693475105",
      "securityIdType": "CUSIP",
      "symbol": "PNC",
      "units": 100
    }
  ]
}

Supported data elements

Note

Investments product responses vary by account category.

Calls to this endpoint for annuity, deposit, insurance, line of credit, or loan account categories return data included in the Balances product.

All account categories

includes:

Name	Required	Description
account info	true	Includes account info data elements
balances	true	Includes balances data elements

Investment accounts

may also include:

Name	Type	Description
holdings	[holding]	Array of holdings
openOrders	[openOrder]	Array of open orders
contribution	[contribution]	Describes how new contributions are distributed among the available securities
vesting	[vesting]	Provides the past, present, and future vesting schedule and percentages
investmentLoans	[investmentLoan]	Array of investment loans
pensionSource	[pensionSource]	Array of Pension Source
equityGrants	[equityGrants]	Array of equity grants

Holding

Name	Type	Description
anonymous	object	none
assetClasses	array	Percent breakdown by asset class.
assetClasses.assetClass	string	none
assetClasses.percent	number	Percentage of asset class that falls under this asset
averageCost	boolean	Cost is average of all purchases for holding.
cashAccount	boolean	If true, indicates that this holding is used to maintain proceeds from sales, dividends, and other cash postings to the investment account.
changeInPrice	number	Change in current price compared to previous day's close
currency	[currency]	none
currentUnitPrice	number	none
currentUnitPriceDate	string(date-time)	Current unit price as of date
debtSecurity	object [debtSecurity]	Information about the security specific to the type of security
debtSecurity.parValue	number	Par value amount
debtSecurity.debtType	string	Debt type. COUPON, ZERO.
debtSecurity.debtClass	string	Classification of debt. TREASURY, MUNICIPAL, CORPORATE, OTHER.
debtSecurity.couponRate	number	Bond coupon rate for next closest call date
debtSecurity.couponDate	string(date-time)	Maturity date for next coupon
debtSecurity.couponMatureFrequency	string	When coupons mature. MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL, or OTHER.
debtSecurity.callPrice	number	Bond call price
debtSecurity.yieldToCall	number	Yield to next call
debtSecurity.callDate	string(date-time)	Next call date
debtSecurity.callType	string	Type of next call. CALL, PUT, PREFUND, MATURITY.
debtSecurity.yieldToMaturity	number	Yield to maturity
debtSecurity.bondMaturityDate	string(date-time)	Bond Maturity date
description	string	Description of the holding
expirationDate	string(date-time)	For CDs, bonds, and other time-based holdings.
faceValue	number	Required for bonds. Face value at the time of data retrieved.
fiAssetClasses	array	Percent breakdown by FI-specific asset class percentage breakdown
fiAssetClasses.assetClass	string	FI-specific asset class
fiAssetClasses.percent	number	Percentage of asset class that falls under this asset
fiAttributes	array [fiAttribute]	[Data provider-specific attribute]
heldInAccount	string	Sub-account
holdingId	string	Long term persistent identity of the holding
holdingName	string	Holding name or security name
holdingSubType	string	none
holdingType	string	none
inv401kSurce	string	Source for money for this security.
marketValue	number	Market value at the time of data retrieved
mutualFundSecurity	object [mutualFundSecurity]	Information about the security specific to the type of security
mutualFundSecurity.mutualFundType	string	Mutual fund type. OPENEND, CLOSEEND, OTHER.
mutualFundSecurity.unitsStreet	number	Units in the FI's street name, positive quantity
mutualFundSecurity.unitsUser	number	Units in user's name directly, positive quantity
mutualFundSecurity.reinvestDividends	boolean	Reinvest dividends
mutualFundSecurity.reinvestCapitalGains	boolean	Reinvest capital gains
mutualFundSecurity.yield	number	Current yield reported as portion of the fund's assets
mutualFundSecurity.yieldAsOfDate	string(date-time)	As-of date for yield value
originalPurchaseDate	string(date-time)	Date of original purchase
optionSecurity	object [optionSecurity]	Information about the security specific to the type of security
optionSecurity.secured	string	How the option is secured. NAKED, COVERED.
optionSecurity.optionType	string	PUT or CALL
optionSecurity.strikePrice	number	Strike price / Unit price
optionSecurity.expireDate	string(date-time)	Expiration date of option
optionSecurity.sharesPerContract	number	Shares per contract
otherSecurity	object [otherSecurity]	Information about the security specific to the type of security
typeDescription	string	Description of Other Security. Required if otherSecurity is included
positionType	string	LONG, SHORT.
purchasedPrice	number	Price of holding at the time of purchase
rate	number	For CDs, bonds, and other rate based holdings.
securityId	string	Unique identifier of security
securityIdType	string	Security identifier type
stockSecurity	object [stockSecurity]	Information about the security specific to the type of security
stockSecurity.unitsStreet	number	Units in the FI's street name, positive quantity
stockSecurity.unitsUser	number	Units in user's name directly, positive quantity
stockSecurity.reinvestDividends	boolean	Reinvest dividends
stockSecurity.stockType	string	COMMON, PREFERRED, CONVERTIBLE, OTHER
stockSecurity.yield	number	Current yield
stockSecurity.yieldAsOfDate	string(date-time)	Yield as-of date
sweepSecurity	object [sweepSecurity]	Information about the security specific to the type of security
sweepSecurity.currentBalance	number	Balance of funds in account
sweepSecurity.availableBalance	number	Balance of funds available for use
sweepSecurity.balanceAsOf	string(date-time)	As-of date of balances
sweepSecurity.checks	boolean	Whether or not checks can be written on the account
symbol	string	Ticker / Market symbol
taxLots	array [object]	Breakdown by tax lot.
taxLots.costBasis	number	Total amount of money spent acquiring this lot including any fees or commission expenses incurred.
taxLots.currentValue	number	Lot market value
taxLots.originalPurchaseDate	string(date-time)	Lot acquired date.
taxLots.postionType	string	LONG, SHORT.
taxLots.purchasedPrice	number	Original purchase price.
taxLots.quantity	number	Lot quantity.
units	number	Required for stock, mutual funds. Number of shares (with decimals).

Contribution

Name	Type	Description
securityId	string	Unique identifier of security
securityIdType	string	Security identifier type CUSIP, ISIN, SEDOL, SICC, VALOR, WKN
employerMatchPercentage	number	Employer contribution match percentage
employerMatchAmount	number	Employer contribution match amount
employeePreTaxAmount	number	Employee pre‐tax contribution amount
employeePreTaxPercentage	number	Employee pre‐tax contribution percentage
employeeAfterTaxAmount	number	Employee after tax contribution amount
employeeAfterTaxPercentage	number	Employee after tax contribution percentage
employeeDeferPreTaxAmount	number	Employee defer pre‐tax contribution match amount
employeeDeferPreTaxPercentage	number	Employee defer pre‐tax contribution match percentage
employeeYearToDate	number	Employee total year to date contribution
employerYearToDate	number	Employer total year to date contribution
rolloverContributionPercentage	number	Rollover contribution percentage
rolloverContributionAmount	number	Rollover contribution Amount

EquityGrants

Name	Type	Description
grantId	string	Unique identifier of grant.
grantDate	string(date-time)	Date grant was given.
grantType	string	Type of grant.
seqNum	number	Sequence number.
grantPrice	number	Grant price.
grantCurrencyCode	string	Indicates the currency of grant USD vs AUD vs EUR, etc. (for share awards, you will still get a USD).
quantityGranted	number	Number of options.
quantityOutstanding	number	Outstanding quantity.
expirationDate	string(date-time)	Date grant expires.
vestings	array	An array of equityGrant.vestings. Provides the past, present, and future vesting schedule and percentages.
vestings.vestedQuantity	number	Vested quantity (Vested shares total qty of vesting tranche)
vestings.vestedValue	number	Vested balance at grant (aggregate of all vestings).
vestings.vestingDate	string(date-time)	Vesting date
vestings.vestExpireDate	string(date-time)	Expiration date, i.e., forfeited unless exercised by this date
vestings.vestedStatus	string	Valid, active, or cancelled

InvestmentLoan

Name	Type	Description
loanId	string	Unique identifier for this loan
loanDescription	string	Description
initialLoanBalance	number	Initial loan balance amount
loanStartDate	string(date-time)	Start date of the loan
currentLoanBalance	number	Current loan principal balance amount
dateAsOf	string(date-time)	Date and time of current loan balance
loanRate	number	Loan annual interest rate for the loan
loanPaymentAmount	number	Loan payment amount
loanPaymentFrequency	string	WEEKLY, BIWEEKLY, TWICEMONTHLY, MONTHLY,FOURWEEKS, BIMONTHLY, QUARTERLY, SEMIANNUALLY, ANNUALLY, OTHER.
loanPaymentInitial	number	Initial number of loan payments
loanPaymentsRemaining	integer	Remaining number of loan payments
loanMaturityDate	string(date-time)	Expected loan end date
loanInterestToDate	number	Total interest paid to date on this loan
loanTotalProjectedInterest	number	Total projected interest to be paid on this loan
loanNextPaymentDate	string(date-time)	The next payment date for the loan

OpenOrder

Name	Type	Description
orderId	string	Long term persistent identity of the order. Id for this order transaction.
securityId	string	Unique identifier of security.
securityIdType	string	Security identifier type. CUSIP, ISIN, SEDOL, SICC, VALOR, WKN.
symbol	string	Market symbol
description	string	Description of order
units	number	number of units (shares or bonds etc)
orderType	string	BUY, SELL, BUYTOCOVER, BUYTOOPEN, SELLTOCOVER, SELLTOOPEN, SELLSHORT, SELLCLOSE.
orderDate	string(date-time)	Order date
unitPrice	number	Unit price
unitType	string	SHARES, CURRENCY.
orderDuration	string	This order is good for DAY, GOODTILLCANCEL, IMMEDIATE
subAccount	string	CASH, MARGIN, SHORT, OTHER.
limitPrice	number	Limit Price
stopPrice	number	Stop price
inv401kSource	string	For 401(k) accounts, source of money for this order. PRETAX, AFTERTAX, MATCH, PROFITSHARING, ROLLOVER, OTHERVEST, OTHERNONVEST. Default if not present is OTHERNONVEST.

PensionSource

Name	Type	Description
displayName	string	Name of the Source
amount	number	Benefit Amount
paymentOption	string	Form of payment
asOfDate	string(date-time)	Date benefit was calculated
frequency	string	Allowed values: ANNUALLY, BIWEEKLY, DAILY, MONTHLY, SEMIANNUALLY, SEMIMONTHLY, WEEKLY
startDate	string(date-time)	Assumed retirement date ‐ As of date amount is payable

Vesting

Name	Type	Description
vestingDate	string(date-time)	Vesting date
symbol	string	Security symbol
strikePrice	number	Strike price
vestingPercentage	number	Vesting percentage
otherVestAmount	number	Other vest amount
otherVestPercentage	number	Other vest percentage
vestedBalance	number	Vested balance
unVestedBalance	number	Unvested balance
vestedQuantity	number	Vested quantity
unVestedQuantity	number	Unvested quantity

Example response
Supported data elements

Transactions Accounts

Introduction

Technical Guides

Sandbox Data

Reference

Overview

Akoya Token API v2.2.0

Akoya Service Token API v1.0.1

Akoya APIs v2.3.0

Akoya Apps Management API v2.0.0

Akoya Notifications API v1.1.0

Akoya Consent API v1.1.0

Investments guide

Table of contents

Investments guide

Example response

Data elements shown are not exhaustive

JSON

Supported data elements

Note

All account categories

Investment accounts

Holding

Contribution

EquityGrants

InvestmentLoan

OpenOrder

PensionSource

Vesting

Table of contents