Transactions 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 Transactions API offers historical and current transactions, transaction types, amounts, dates and descriptions. Include it with all account categories except annuityAccount.
Transactions returns results in JSON in FDX format.
Use Cases
Business & Financial Management: Aggregate their financial accounts in one place (in conjunction with Balances and Statements).
Lending & Credit Enhancement: Access bank or brokerage data to better inform lending decisions (in conjunction with Balances, Customers, and Statements).
Wealth Management & Investing: 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 Balances and Transactions).
Security
The Transactions 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, Transactions operates in both sandbox and prod:
Sandbox:
https://sandbox-products.ddp.akoya.com
Production:
https://products.ddp.akoya.com
Endpoints
Transactions
GET /transactions/{version}/{providerId}/{accountId}
This endpoint allows you to retrieve transaction history of consumer-permissioned accounts.
Path Params
Param | Description |
|---|---|
{version} | Major API version (e.g. v3) |
{providerId} | ID for the financial institution providing the data |
{accountId} | The consumer’s unique account identifier (not the account number) |
Query Params
Param | Type | Required | Description |
|---|---|---|---|
mode | String | No | BETA. Default is raw. Use standard for FDX-aligned, standardized data values. |
startTime | String | No | ISO 8601 date format in UTC time zone. If blank, the API uses a default value (current date - 15 calendar days). If you specify a value, you must also include endTime. |
endTime | String (Date-Time) | No | ISO 8601 date format in UTC time zone. If blank, the API uses a default value (current date). If you specify a value, you must also include startTime. |
offset | String | No | The number of items to skip before the first in the response. The default is 0. |
limit | String | No | The maximum number of items to be returned in the response. The default is 50. |
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. |
content-type | String | No | Application/JSON |
Example Response
JSON
Supported Data Elements
All Account Categories
May include:
Name | Type | Description |
|---|---|---|
accountId | String | Corresponds to accountId in Account Info, Balances, and Investments responses. |
amount | Number | The amount of money in the account currency. If balanceType is ASSET: 1. If debitCreditMemo = DEBIT, sign is "+" or not present 2. If CREDIT, sign is "-" If balanceType is LIABILITY: 1. If debitCreditMemo = DEBIT, sign is "-" 2. If CREDIT, sign is "+" or not present |
category | String | Transaction category, preferably MCC or SIC. |
debitCreditMemo | String | The posting type of a transaction |
description | String | The description of the transaction |
imageIds | [String] | Array of image identifiers (unique to transaction) used to retrieve images of check or transaction receipt. |
fiAttributes | Array [fiAttribute] | Array of FI-specific attributes |
foreignAmount | Number | The amount of money in the foreign currency |
foreignCurrency | String | The ISO 4217 code of the foreign currency |
lineItem | Array [lineItem] | Breakdown of the transaction details |
links | Array [hateoasLink] | Links (unique to this Transaction) used to retrieve images of checks or transaction receipts, or invoke other APIs |
memo | String | Secondary transaction description |
postedTimestamp | String (Date-Time) | The date and time that the transaction posted to the account. If you don't provide it, TransactionTimestamp can be used as PostedTimeStamp. |
reference | String | A tracking reference identifier |
referenceTransactionId | String | For reverse postings, the identity of the transaction this posting reverses. For the correction transaction, the identity of the reversing post. For credit card posting transactions, the identity of the authorization transaction. |
status | String | AUTHORIZATION, MEMO, PENDING, or POSTED |
subCategory | String | Transaction category detail |
transactionId | String | Long term persistent identity of the transaction (unique to account). Transaction IDs should: 1. be the same for pending and posted 2. be different for reversed transactions 3. referenceTransactionId should be present for reversed transactions' |
transactionTimestamp | String (Date-Time) | The date and time that the server backend systems added the transaction. |
Deposit Transactions
May also include:
Name | Type | Description |
|---|---|---|
payee | String | Payee name |
checkNumber | Integer | Check Number |
transactionType | String | depositTransaction type: CHECK, WITHDRAWAL, TRANSFER, POSDEBIT, ATMWITHDRAWAL, BILLPAYMENT, FEE, DEPOSIT, ADJUSTMENT, INTEREST, DIVIDEND, DIRECTDEPOSIT, ATMDEPOSIT, POSCREDIT |
Insurance Transactions
May also include:
Name | Type | Description |
|---|---|---|
transactionType | String | insuranceTransaction type: PAYMENT, FEE, ADJUSTMENT, INTEREST |
Investment Transactions
May also include:
Name | Type | Description |
|---|---|---|
accruedInterest | Number | Accrued interest. |
commission | Number | Transaction commission. |
confirmationNumber | String | Confirmation number of the transaction. |
faceValue | Number | Cash value for bonds. |
fees | Number | Fees applied to the trade. |
fractionalCash | Number | Cash for fractional units (used for stock splits). |
gain | Number | For sales. |
incomeType | String | Type of investment income. CGLONG (capital gains-long term), CGSHORT (capital gains-short term), MISC. |
inv401kSource | String | Source of money. |
load | Number | Load on the transaction. |
loanId | String | For 401k accounts only. This indicates the transaction was due to a loan or a loan repayment. |
loanInterest | Number | How much loan pre-payment is interest. |
loanPrincipal | Number | How much loan pre-payment is principal. |
markup | Number | Portion of the unit price the dealer adds as markup. |
newUnits | Number | Number of shares after split. |
oldUnits | Number | Number of shares before split. |
payrollDate | String | Payroll obtained the date for the 401k transaction. |
penalty | Number | Indicates amount withheld due to a penalty. |
positionType | String | |
price | Number | Unit purchase price. |
priorYearContrib | Boolean | Indicates whether this buy used a prior year's contribution. TRUE or FALSE. |
runningBalance | Number | Running balance of the position. |
securityId | String | Unique identifier of security. |
securityIdType | String | Security identifier type. |
securityType | String | |
shares | Number | Required for stock, mutual funds. Number of shares (with decimals). Negative numbers indicate securities leaving the account. |
splitRatioDenominator | Number | Split ratio denominator. |
splitRatioNumerator | Number | Split ratio numerator. |
stateWithholding | Number | State tax withholding. |
subAccountFund | String | From which account money came in. |
subAccountSec | String | Sub-account security type. |
symbol | String | Ticker symbol. |
taxes | Number | Taxes on the trade. |
taxExempt | Boolean | Tax-exempt transaction TRUE or FALSE. |
transactionReason | String | Reason for this transaction; CALL (the debt was called), SELL (the account sold the debt), MATURITY (the debt reached maturity) |
transactionType | String | investmentTransaction type: PURCHASED, SOLD, PURCHASEDTOCOVER, ADJUSTMENT, PURCHASETOOPEN, PURCHASETOCLOSE, SOLDTOOPEN, SOLDTOCLOSE, INTEREST, MARGININTEREST, REINVESTOFINCOME, RETURNOFCAPITAL, TRANSFER, CONTRIBUTION, FEE, OPTIONEXERCISE, OPTIONEXPIRATION, DIVIDEND, DIVIDENDREINVEST, SPLIT, CLOSURE, INCOME, EXPENSE, CLOSUREOPT, INVEXPENSE, JRNLSEC, JRNLFUND, OTHER, DIV, SRVCHG, DEP, DEPOSIT, ATM, POS, XFER, CHECK, PAYMENT, CASH, DIRECTDEP, DIRECTDEBIT, REPEATPMT |
transferAction | String | Transfer direction. |
unitPrice | Number | Price per commonly-quoted unit. Does not include markup/markdown, unitprice. Share price for stocks, mutual funds, and others. Percentage of par for bonds. Per share (not contract) for options. |
units | Number | For security-based actions other than stock splits, quantity. Shares for stocks, mutual funds, and others. Face value for bonds. Contracts for options. |
unitType | String | None |
withholding | Number | Federal tax withholding. |
Line of Credit Transactions
May also include:
Name | Type | Description |
|---|---|---|
checkNumber | Integer | Check number |
paymentDetails | Array [paymentDetails] | Payment details for some transactions |
paymentDetails.escrowAmount | Number | The amount of payment applied to escrow |
paymentDetails.feesAmount | Number | The amount of payment applied to fees |
paymentDetails.insuranceAmount | Number | The amount of payment applied to life/health/accident insurance on the loan |
paymentDetails.interestAmount | Number | The amount of payment applied to interest |
paymentDetails.pmiAmount | Number | The amount of payment applied to PMI |
paymentDetails.principalAmount | Number | The amount of payment applied to principal |
transactionType | String | locTransaction type: CHECK, WITHDRAWAL, TRANSFER, POSDEBIT, ATMWITHDRAWAL, BILLPAYMENT, FEE, DEPOSIT, ADJUSTMENT, INTEREST, DIVIDEND, DIRECTDEPOSIT, ATMDEPOSIT, POSCREDIT |
Loan Transactions
May also include:
Name | Type | Description |
|---|---|---|
paymentDetails | Array [paymentDetails] | Payment details for some transactions |
paymentDetails.escrowAmount | Number | The amount of payment applied to escrow |
paymentDetails.feesAmount | Number | The amount of payment applied to fees |
paymentDetails.insuranceAmount | Number | The amount of payment applied to life/health/accident insurance on the loan |
paymentDetails.interestAmount | Number | The amount of payment applied to interest |
paymentDetails.pmiAmount | Number | The amount of payment applied to PMI |
paymentDetails.principalAmount | Number | The amount of payment applied to principal |
transactionType | String | loanTransaction type: ADJUSTMENT, FEE, INTEREST, PAYMENT |
Error Responses
See our error documentation.