Statements Guide
Allows retrieval of up to 2 years' of historical statements for your consumer's consented accounts
Version Differences
This endpoint is available in API versions 2 and 3. Note the following differences:
Area | V2 | V3 |
|---|---|---|
x-akoya-interaction-type header | Optional | Required |
x-akoya-last-access header | Not Supported | Required |
x-akoya-intent-type header | Not Supported | Required |
Overview
The Statements product allows retrieval of statements for your consumer's consented accounts. A date range of up to two years of historical statements is available. Note: Maximum date ranges vary by provider.
Paginated Statement list results include an array of statement information with the consumer's account identifier and details such as statement id, date, description, and status. The results also include links to GET the statement, returned in PDF format.
Use Cases
Business & Personal Financial Management: Aggregate all financial accounts in one place (in conjunction with Balances and Transactions).
Lending & Credit Enhancement: Access bank or brokerage data to better inform lending decisions (in conjunction with Balances, Transactions, and Customers).
Security
The Statements API requires authentication using a bearer token (id_token assigned to the permissioned user). Include the id_token in the Authorization header of each request. The actual token lifetime varies by provider, but assume a lifetime of 15 minutes and code your application to automatically refresh the token if it has expired.
Base URL
Like all Akoya APIs, Statements operates in both sandbox and prod:
Sandbox:
https://sandbox-products.ddp.akoya.com
Production:
https://products.ddp.akoya.com
Endpoints
Statement List
GET /statements/{version}/{providerId}/{accountId}
Retrieves a list of available statements for the consumer's consented accounts. A date range of up to two years of historical statements is available. Note: Maximum date ranges vary by provider.
Path Params
Param | Description |
|---|---|
{version} | Major API version (Example: v3) |
{providerId} | ID for the financial institution providing the data |
{accountId} | The consumer’s unique account identifier (not the account number) |
Query Params
Param | Type | Required | Description |
|---|---|---|---|
startTime | String (Date-Time) | No | Start date for use in retrieval of statements (ISO 8601) |
endTime | String (Date-Time) | No | End date for use in retrieval of statements (ISO 8601) |
offset | String | No | The number of items to skip before the first in the response. The default value is 0. |
limit | String | No | The maximum number of items to be returned in the response The default value is 50. |
Headers
Header | Type | Required | Description |
|---|---|---|---|
Authorization | String | Yes | The ID Token for the permissioned user |
x-akoya-interaction-type | String (Enum) | v2: No v3: Yes | Indicates whether a consumer action prompted the request (USER) or the request is part of a batch process (BATCH) |
x-akoya-last-access | String (Date-Time) | v2: N/A v3: Yes | The date and time stamp for the last active use by the user |
x-akoya-intent-type | String (Enum) | v2: N/A v3: Yes | Indicates whether a transaction involves a payment Acceptable values are payments or nonpayments |
Example Response
JSON
How to Read the Statement List Response
To provide a consistent way to link each statement provided in the list, Akoya includes the exact API call for retrieving each statement. By providing these calls, Akoya allows a passthrough of the statement since direct connections to providers cannot be made. Akoya also interprets any special characters in statement metadata and tokenizes the statementId.
Use the href link created in the response.
Note: If you’re testing using Postman, you may use the tokenized statementId value included in statements.links.href.
Supported Data Elements
Name | Type | Description |
|---|---|---|
accountId | String | Corresponds to accountId in Account entity |
statementId | String | Long-term persistent identity of the statement |
statementDate | String (Date-Time) | Date of the statement (ISO 8601) |
description | String | Description of statement |
status | String | Defines the status of a document |
link | Object {hateoasLink} | The statement download link hosted by Akoya |
Statement
GET /statements/{version}/{providerId}/{accountId}/{statementId}
Retrieve a specific account statement file. Use HTTP Accept request-header to specify desired content types.
Path Params
Param | Description |
|---|---|
{version} | Major API version (Example: v3) |
{providerId} | ID for the financial institution providing the data |
{accountId} | The consumer’s unique account identifier (not the account number) |
{statementId} | The desired statement ID returned from the Statement List endpoint |
Query Params
Param | Type | Required | Description |
|---|---|---|---|
(None) | --- | --- | --- |
Headers
Header | Type | Required | Description |
|---|---|---|---|
Authorization | String | Yes | The ID Token for the permissioned user |
x-akoya-interaction-type | String (Enum) | v2: No v3: Yes | Indicates whether a consumer action prompted the request (USER) or the request is part of a batch process (BATCH) |
x-akoya-last-access | String (Date-Time) | v2: N/A v3: Yes | The date and time stamp for the last active use by the user |
x-akoya-intent-type | String (Enum) | v2: N/A v3: Yes | Indicates whether a transaction involves a payment Acceptable values are payments or nonpayments. |
Example Response
(An image of an account statement in PDF format)
How to Use the Statements Product
Step 1: Call Statement List
To get statements for your consumer, first retrieve a list of available statements for the consented account. Your request may include a date range of up to two years of historical statements (maximum date ranges vary by provider).
JSON
Step 2: Call Statement
From the statement list response, use statements.links.href as the location in the cURL command. To save the response to pdf, include the output command with a file name.
JSON
Error Responses
See our error documentation.