Coming soon

Akoya API v3 (sandbox release)

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

We are projecting February 23rd to release v3 into production.

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	Money Movement Direction	Applicable Products
Initial account linking	FROM consumer's account	Payments, Customers, Balances, and Investments
Performing a money movement transaction.	FROM consumer's account (e.g. ACH debit)	Payments, Balances, and Investments
Performing the last balance check for a payment within a rolling 24-hour period	N/A	Balances and Investments

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

Scenario	Money Movement Direction	Applicable Products
Performing a money movement transaction	INTO consumer's account (e.g. ACH credit)	All
All other use cases not involving: 1. Money movement transactions out of an account 2. Account linking for payments	N/A	All

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 in one of the following products: Payments, Balances, Investments, Customers	`nonpayments`