Coming soon

Akoya API v3

Version 3 of our APIs will be released in the sandbox environment on January 15, 2026 and will be live in production on . This new version introduces two new mandatory headers and makes an existing previously optional header mandatory. This is a breaking change.

Timeline

All recipients must migrate to v3 by . Version 2 of our APIs will be sunset at that time.

Summary of Changes

This existing header will be mandatory:

x-akoya-interaction-type

Two new mandatory headers will be introduced:

x-akoya-intent-type (for all apps using the Payments API)
x-akoya-last-access

The version number in the API base path will change to v3 to accommodate the major version change..

Example: https://sandbox-products.ddp.akoya.com/accounts-info/v3/mikomo

Rationale

Akoya is implementing updates to the Akoya Data Access Network to ensure clearer context, improved data quality, accommodate requested reporting to data providers, and ensure more consistent performance across the ecosystem.

Technical Overview

x-akoya-interaction-type Header

This header will now be mandatory. Accepted values remain USER or BATCH.

Example: “x-akoya-interaction-type=BATCH”

If the request is prompted by user action, use USER as the value. If the request is part of a batch process, use BATCH.

x-akoya-intent-type Header

This new header indicates whether a call is involved in a payments use case.

This information may be shared with data providers that require visibility into payments-related activity.
There are two allowed values:

payments
nonpayments

This header is required if you are subscribed to the Payments API. If the header is omitted or contains an invalid value, Akoya will return an error.

This header is optional if you are not subscribed to the Payments API. If you choose to provide it, the value should always be nonpayments.

If you are subscribed to the Payments endpoint, you must use the value payments for the following use cases:

Scenario	Applicable to (Endpoints)
At initial account linking if the intent will be to facilitate money movement transactions from the user’s account.	Payments, Customer Information, Account Holder Information, Balances, and Investments
When facilitating a money movement transaction that moves money from a user’s account (Example: ACH debit).	Payments, Balances, and Investments
When performing the last balance check API request within a rolling 24-hour period in support of a single money movement transaction	Balances and Investments

You must use the value nonpayments for the following use cases:

Scenario	Applicable to (Endpoints)
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)	All
API calls only used to facilitate money movement transactions into a user’s account (Example: ACH credit), provided that you are able to identify that the calls relate to this scenario.	Payments

x-akoya-last-access Header

The value for this header is 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

curl -X GET \
"https://sandbox-products.ddp.akoya.com/payments/v3/mikomo/<ACCOUNT_ID>/payment-networks" \
  -H "authorization: Bearer <ID_TOKEN>" \
  -H "x-akoya-interaction-type: user" \
  -H "x-akoya-intent-type: payments" \
  -H "x-akoya-last-access: 2025-01-14T15:21:00Z"

Balances

Making a balance check

curl -X GET \
  "https://sandbox-products.ddp.akoya.com/balances/v3/mikomo" \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "x-akoya-interaction-type: user" \
  -H "x-akoya-intent-type: payments" \
  -H "x-akoya-last-access: 2025-01-14T15:21:00Z"

Account Information

curl -X GET \
  "https://sandbox-products.ddp.akoya.com/accounts-info/v3/mikomo" \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "x-akoya-interaction-type: user" \
  -H "x-akoya-intent-type: nonpayments" \
  -H "x-akoya-last-access: 2025-01-14T15:21:00Z"

Example Use Cases

Scenario	Header Value	Comments
Call to Payments at account linking	`payments`	Exception: Use `nonpayments`If you intend money movement into the user's account and are able to identify that the call relates to that scenario.
Call to the Customer Info or Account Holder Information endpoint at account linking when you are subscribed to the Payments API	`payments`	Exception: Use `nonpayments`If you intend money movement into the user's account and are able to identify that the call relates to that scenario.
Call to the Balances or Investments endpoint at account linking when you are also subscribed to the Payments endpoint (initial balance check)	`payments`	Exception: Use `nonpayments`If you intend money movement into the user's account and are able to identify that the call relates to that scenario.
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`	“Payments” intent must be applied only once in a rolling 24-hour window in support of a single payment.
Call to the Account Information endpoint	`nonpayments`
Call made to the Payments, Balances, Investments, Customer info, or Account Holder Information endpoints IF the call is: * Unrelated to a money movement out of the user’s account and: * 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 if you are not subscribed to Payments	`nonpayments`
Any call to an endpoint that is NOT one of the following: Payments, Balances, Investments, Customer Info, Account Holder Information.	`nonpayments`