Balances Guide
Version Differences
This endpoint is available in API versions 2 and 3. Note the following differences:
Area | V2 | V3 |
|---|---|---|
x-akoya-interaction-type header | Optional | Required |
x-akoya-last-access header | Not Supported | Required |
x-akoya-intent-type header | Not Supported | Required |
Overview
The Akoya Balances product combines basic consumer account information with the latest, actionable financial account data including: available balance, payment amounts, due dates, credit card rewards details, limits, due dates, year-to-date interest, and more.
The Balances endpoint returns all data available in the Account info product plus data such as current balance, payment dates, and other data. To use this product, you must have the consumer’s consent and their associated ID token for permissioned data.
Balances returns results in JSON in FDX format. Balances include a common grouping of data and may contain additional data elements for annuity, deposit, insurance, investment, line of credit, or loan account categories.
Common Use Cases
Account Opening: Open and fund accounts without micro-deposits (in conjunction with Payments and Customers).
Personal & Business Financial Management: Manage personal and business accounts (in conjunction with Transactions and Statements).
Lending & Credit Enhancement: Access bank or brokerage data to better inform lending decisions (in conjunction with Transactions, Statements, and Customers).
Payment Enablement: Authorize account-to-account or person-to-person payments with instant account authentication (in conjunction with Payments and Customers).
Wealth Management: Give users and/or financial advisors the ability to collate investments, assets, and other held-away account information for one sweeping financial picture (in conjunction with Transactions and Investments).
Security
The Balances API requires authentication using a bearer token (id_token assigned to the permissioned user). You should include the id_token in the Authorization header of each request. The actual token lifetime varies by provider, but assume a lifetime of 15 minutes and code your application to automatically refresh the token if it has expired.
Base URL
Like all Akoya APIs, Balances operates in both sandbox and prod:
Sandbox:
https://sandbox-products.ddp.akoya.com
Production:
https://products.ddp.akoya.com
Endpoints
Balances
GET /balances/{version}/{providerId}
Retrieves balance information for a permissioned user's account
Path Params
Param | Description |
|---|---|
{version} | Major API version (e.g. v3) |
{providerId} | ID for the financial institution providing the data |
Query Params
Param | Type | Required | Description |
|---|---|---|---|
mode | String | No | BETA. Default is raw. Use standard for FDX-aligned, standardized data values. |
accountIds | String | No | Comma separated list of consumer account ids |
Headers
Header | Type | Required | Description |
|---|---|---|---|
Authorization | String | Yes | The ID Token for the permissioned user |
x-akoya-interaction-type | String (Enum) | v2: No v3: Yes | Indicates whether a consumer action prompted the request (USER) or the request is part of a batch process (BATCH). |
x-akoya-last-access | String (Date-Time) | v2: N/A v3: Yes | The date and time stamp for the last active use by the user. |
x-akoya-intent-type | String (Enum) | v2: N/A v3: Yes | Indicates whether a transaction involves a payment. Acceptable values are payments or nonpayments. |
Example Response
JSON
Supported Data Elements
All Account Categories
Include:
Name | Required | Description |
|---|---|---|
account info | true | Includes account info data elements |
Deposit Accounts
May also include:
Name | Type | Description |
|---|---|---|
balanceAsOf | String (Date-Time) | As-of date of balances |
openingDayBalance | Number | Day's opening fund balance |
availableBalance | Number | Balance of funds available for use |
interestYtd | Number | YTD Interest |
currentBalance | Number | Balance of funds in account |
Loan Accounts
May also include:
Name | Type | Description |
|---|---|---|
balanceAsOf | String (Date-Time) | As-of date of balances |
escrowBalance | Number | Escrow balance of loan |
interestPaidYearToDate | Number | Interest paid year to date |
lastPaymentAmount | Number | Last payment amount |
lastPaymentDate | String (Date-Time) | Last payment date |
nextPaymentAmount | Number | Amount of next payment |
nextPaymentDate | String (Date-Time) | Date of next payment |
originalPrincipal | Number | Original principal of loan |
payOffAmount | Number | Payoff amount |
principalBalance | Number | Principal balance of loan |
Line of Credit Accounts
May also include:
Name | Type | Description |
|---|---|---|
balanceAsOf | String (Date-Time) | As-of date of balances |
advancesApr | Number | Advances APR |
availableCash | Number | Available cash |
availableCredit | Number | Available credit |
cashAdvanceLimit | Number | Cash advance limit |
creditLine | Number | Credit limit |
currentBalance | Number | Current balance LOC |
currentRewardsBalance | Number | Current rewards balance |
financeCharges | Number | Finance charges |
lastPaymentAmount | Number | Last payment amount |
lastPaymentDate | String (Date-Time) | Last payment date |
lastStmtBalance | Number | Last Statement Balance |
lastStmtDate | String (Date-Time) | Last Statement Date |
minimumPaymentAmount | Number | Minimum payment amount |
nextPaymentAmount | Number | Amount of next payment |
nextPaymentDate | String (Date-Time) | Due date of next payment |
pastDueAmount | Number | Past Due Amount |
pointsAccrued | Number | Points accrued |
principalBalance | Number | Principal balance |
pointsRedeemed | Number | Points redeemed |
purchasesApr | Number | Purchases APR |
Investment Accounts
may also include:
Name | Type | Description |
|---|---|---|
availableCashBalance | Number | Cash balance across all sub-accounts. Should include sweep funds. |
balanceAsOf | String (Date-Time) | As-of date of balances |
balanceList | Array | Array of balanceList objects. |
currentValue | Number | Total current value of all investments |
dailyChange | Number | Daily change |
marginBalance | Number | Margin balance |
percentageChange | Number | Percentage change |
rolloverAmount | Number | Rollover amount |
shortBalance | Number | Short balance |
balanceList
Name | Type | Description |
|---|---|---|
balanceName | String | Name of the balance. |
balanceDescription | String | Description of balance. |
balanceType | String | The type of an investment balance. AMOUNT or PERCENTAGE. |
balanceValue | Number | Value of balance name. |
balanceDate | String (Date-Time) | Date as of this balance. |
currency | Object {currency} | currency object which may include currencyRate, currencyCode, and originalCurrencyCode |
Insurance Accounts
May also include:
Name | Type | Description |
|---|---|---|
policyCoverageAmount | Number | Total amount the policy insures the user for. |
policyEndDate | String (Date-Time) | The premium end date. |
policyPremium | Number | The amount of the user's premium. |
policyPremiumTerm | String | The payment term for the premium. MONTHLY or ANNUAL. |
policyStartDate | String (Date-Time) | The premium start date. |
Annuity Accounts
May also include:
FDX 5 deprecates all of the elements in this table, and FDX 6 will remove them.
Name | Type | Description |
|---|---|---|
annualIncrease | Number | Percent or dollar amount of annual payment increase |
annualIncreaseType | String | FIXED, PERCENT, DOLLAR. Deprecated, FDX 6.0 will remove it. |
netPresentValue | Number | Surrender or cash balance value |
paymentAmount | Number | Amount of the recurring payment |
paymentEndDate | String (Date-Time) | Last payment date |
paymentStartDate | String (Date-Time) | Date of first payment; could be a future date |
periodCertainGuarantee | String | NONE, 5-YEAR, 10-YEAR, 20-YEAR, 30-YEAR. |
totalPaymentCount | Number | Total number of payments the annuity will produce. |
Error Responses
See our error documentation.