Akoya APIs v3 Guide
Akoya released version 3 of the data APIs. Learn about these changes in the following sections.
API Version Update: The Akoya Data API base path is updating from v2 to v3. Token and service APIs remain unchanged.
Summary of Changes
This existing header will be mandatory:
x-akoya-interaction-type
We are introducing two new mandatory headers:
x-akoya-intent-type (for all apps using the Payments API)
x-akoya-last-access
The version number in the API base path is changing to v3.
Example: https://sandbox-products.ddp.akoya.com/accounts-info/v3/mikomo
Rationale
Akoya is implementing updates to the Akoya Data Access Network (Akoya DAN) to ensure clearer context, improved data quality, requested reporting to data providers, and more consistent performance across the ecosystem.
Technical Overview
x-akoya-interaction-type
Mandatory for all recipients. Accepted values remain USER or BATCH.
Example: “x-akoya-interaction-type=BATCH”
Use Cases
Use Case | Header Value |
|---|---|
User action prompted the request | USER |
Request is part of a batch process | BATCH |
x-akoya-intent-type
For apps subscribed to the Payments API, the x-akoya-intent-type header is required. If you omit the header or provide an invalid value, Akoya returns an error.
This is an optional header for all apps that are not subscribed to the Payments API. If provided, the header response for apps not subscribed to the Payments API should always be nonpayments.
This information may be shared with data providers that require visibility into payments-related activity.
There are two allowed values:
payments
nonpayments
Example: “x-akoya-intent-type=payments”
Data recipients must specify x-akoya-intent-type as “payments” for the following use cases and associated data APIs:
At initial account linking for an application subscribed to the Payments endpoint if the intent will be to facilitate money movement transactions from the user’s account. This is applicable to calls made to the Payments, Customer Info, Account Holder Information, Balances, and Investments endpoints.
When facilitating a money movement transaction that moves money from a user’s account (Example: ACH debit). This applies to the Payments, Balances, and Investments endpoints.
When you use the Balances and Investments endpoints are as a balance check for a payment, you should only mark the last balance check API request within a rolling 24-hour period in support of a single money movement transaction as payments.
Data Recipients must specify x-akoya-intent-type as “nonpayments” for the following use cases and associated data APIs:
All other use cases not facilitating money movement transactions out of a data provider account and not related to account linking for payments (Example: personal financial management features).
API calls only used to facilitate money movement transactions into a user’s account (Example: ACH credit), provided that the data recipient is able to identify that such calls relate to a user’s account in this manner.
x-akoya-last-access
The date and time stamp for the last active use by the user. “Last active use” means the user’s last login, logout or active use of your product or service. Follow the ISO8601 date format in the UTC time zone.
Example: “x-akoya-last-access=2025-11-24T00:00:00Z”
Example Calls
Payments
BASH
Balances
Making a balance check:
BASH
Account Information
BASH
Appendix
Example API Call Use Cases
API Call | Header Value | Comments |
|---|---|---|
Call to Payments at account linking | payments | If money movement into the account is intended, the header value should be nonpayment, provided the recipient is able to identify that such calls relate to the account in this way. |
Call to the Customer Info or Account Holder Information endpoint at account linking when the app is also subscribed to the Payments endpoint | payments | If money movement into the account is intended, the header value should be nonpayment, provided the recipient is able to identify that such calls relate to the account in this way. |
Call to the Balances or Investments endpoint at account linking when the app is also subscribed to the Payments endpoint (initial balance check) | payments | If money movement into the account is intended, the header value should be nonpayment, provided the recipient is able to identify that such calls relate to the account in this way. |
Call to the Payments endpoint to facilitate money movement out of the user’s account | payments | |
Last call to the Balances or Investments endpoint to facilitate a money movement out of the user’s account (last balance check before payment) | payments | Apply the "Payments" intent only once in a rolling 24-hour window to support a single payment. |
Call to the Account Information endpoint | nonpayments | |
Call made to the Payments, Balances, Investments, Customer info, and Account Holder Information IF the call is: unrelated to a money movement out of the user’s account and also: unrelated to account linking with a Payments endpoint subscription | nonpayments | |
Call to the Payments endpoint to facilitate a money movement into the user’s account | nonpayments | |
Any call made by an app not subscribed to the Payments endpoint | nonpayments | |
Any call to an endpoint that is NOT one of the following: Payments, Balances, Investments, Customer Info, Account Holder Information. | nonpayments |