Headers

Akoya returns or accepts the following Akoya custom headers.

x-akoya-interaction-id

Unique to each request, Akoya returns an auto-generated interaction identifier in the header of each response. This id may be used for your own logging purposes and as a trace identifier for troubleshooting. When implementing your app, we recommend storing the x-akoya-interaction-id of each response. For more on how x-akoya-interaction-id is used for troubleshooting, see: Troubleshooting.

x-akoya-interaction-type

This header is optional for v2 and required for v3.

You should send the x-akoya-interaction-type header with all Akoya product calls to indicate if the request is part of a batch process or a real-time, consumer interaction. The header is supported by all Akoya product endpoints.

The x-akoya-interaction-type has allowed values user or batch.

user indicates the request is prompted by an end-user action.
batch indicates the request is part of a batch process.

x-akoya-interaction-type allows Akoya to inform any provider which requires this information if a call was made because an end-user initiated an interaction and is awaiting the results, or if it's part of an automated batch job. This allows traffic to be prioritized while maintaining the best possible experience for the end-user.

While x-akoya-interaction-type is optional in Akoya’s v2 product APIs, if a provider requires this header and it is not passed, Akoya will default the header value to batch.

x-akoya-last-access

This header is required in v3 and not applicable for v2.

This header specifies the date and time stamp for the last active use in your app by the consumer. “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”

x-akoya-intent-type

This header is required in v3 for all apps using the Payments API. It's not applicable in v2.

If your app is using the Payments product, this header is required. This is an optional header for all apps that are NOT using the Payments product. If your app does not use Payments and you choose to provide it, the value should always be nonpayments.

There are two allowed values:

payments
nonpayments

When to specify payments

If your app is using Payments, you must specify a value of payments for the following use cases and associated data APIs:

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

Specify nonpayments for the following use cases and associated data APIs:

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

Need Help?

Visit the Support Center in the Data Recipient Hub.

Looking for Provider Nuance Documentation?

All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.

Still Stuck?

For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.