Headers
Akoya returns or accepts the following custom headers.
x-akoya-interaction-id
This header is optional for v2 and v3.
Unique to each request, Akoya returns an auto-generated interaction identifier in the header of each response. You may use this id for your own logging purposes and as a trace identifier for troubleshooting. When implementing your app, consider storing the x-akoya-interaction-id of each response. For more on how Akoya's APIs use x-akoya-interaction-id 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. All Akoya product endpoints support this header.
The x-akoya-interaction-type has allowed values USER or BATCH.
USER indicates that a consumer's action prompted the request.
BATCH indicates the request is part of a batch process.
x-akoya-interaction-type tells providers that require this information whether a consumer initiated the call and is awaiting results, or whether it is part of an automated batch job. This allows traffic to be prioritized while maintaining the best possible experience for the consumer.
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 defaults the header value to BATCH.
x-akoya-last-access
v3 requires this header; v2 does not support it.
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, you must use this header. This header is optional for all apps that do not use 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 |