Accessing Transactional Data
Learn how to access a connected user's transactional data
Transactional data is an enriched list of financial transactions the user has made. Akahu allows you to access this data on behalf of the user.
Prerequisites
Before you can follow this guide, you will need:
- To be able to make requests to the Akahu API (see here for instructions).
- A user access token (
<<apiKey>>
). Follow the Getting Started Guide to obtain one. - Your app access token (
<<appToken>>
). You should get this when you create your app. - An Akahu account with at least one account connected. This account must have transactions, preferably a few so that you can practice filtering them in different ways.
To determine if your account has transactions, make a GET
request to the /accounts
endpoint.
Locate your account in the results and look for the attributes key. If your account attributes include TRANSACTIONS, then the account has transactions.
Making the Request
Using your language of choice, make a GET
request to the https://api.akahu.io/v1/transactions
endpoint, with the following headers:
Authorization: Bearer {{user access token}}
X-Akahu-ID: {{app access token}}
Replace the {{user access token}}
with your user access token, and {{app access token}}
with your app access token.
Handling the response
As in Accessing Account Data, you should handle any HTTP error codes returned by the API.
The API response will look like:
{
"success": true,
"items": [
{
"_id": "trans_1111111111111111111111111",
"_account": "acc_1111111111111111111111111",
"_connection": "conn_1111111111111111111111111",
"created_at": "2020-01-01T01:00:00.000Z",
"updated_at": "2020-01-01T01:00:00.000Z",
"date": "2020-01-01T00:00:00.000Z",
"description": "{RAW TRANSACTION DESCRIPTION}",
"amount": -5.5,
"balance": 100,
"type": "EFTPOS"
}
// ...
],
"cursor": {
"next": "abc123...321cba"
}
}
Breaking down this response:
At the top level, the key success
is true
. That means that the request was successful.
The items
key contains a list of Akahu Transactions, with various information. Different types of accounts have different levels of detail in their transactions, depending on what is available.
The cursor
key allows you to paginate through the results. This allows you to efficiently get transactions for large time-spans, without having to handle gigabyte response sizes. See the section on Pagination below for more information on working with cursors.
Getting a Date Range
Timezones
Akahu's API returns all dates and times in UTC. If no timezone is specified on timestamps in the request, Akahu will assume that the times are also UTC. See here to learn how to specify a timezone in a ISO 8601 date-time string.
By default, the API will return transactions from the last 30 days. If you want to retrieve data for a specific period, you can specify the start
and end
query parameters. These should be ISO 8601 formatted date strings, for example "2020-01-10"
to specify the 10th of January 2020. If you require additional precision, a full ISO 8601 date-time string can be supplied.
Getting Transactions For a Single Account
By default, the API will return transactions from all accounts you have access to. To retrieve transactions from a single account, update the uri to https://api.akahu.io/v1/accounts/{_id}/transactions
, where {_id}
is replaced by the Akahu Account ID you wish to retrieve transactions for.
Enriched Data
If you have permission to view our enriched transactional data, you will see 3 additional fields on your transactions:
outlet
This is the specific outlet the transaction originated from, for example the Four Square in Matakana.merchant
This is the parent company that own the outlet, for example Four Square.category
This is what the transaction has been categorised as.
More detail about these enriched fields can be found in our Transaction Model Documentation
Pagination
For larger queries (those that have many transactions, or span long time-periods), you will probably not receive all transactions for your query at once. Instead, you may only receive the first "page" of results. If a response does not contain all transactions for the provided query, it will also include a "cursor" that points to the next page of results.
To access subsequent pages, simply take the cursor.next
value from each response and make a new request, supplying this value using the cursor
query parameter. In response, you will receive the next page of results, along with a new cursor.next
value.
Once you have reached the final page of results, the value of cursor.next
will be null
. This means that all transactions that match your query have been returned. Passing this null
cursor back to the API will result in an error response.
See below for an example taken from our Javascript SDK:
const query = {
// start: "2021-01-01T00:00:00.000Z",
// end: "2021-01-02T00:00:00.000Z",
};
const transactions = [];
do {
// Transactions are returned one page at a time
const page = await akahu.transactions.list(userToken, query);
// Store the returned transaction `items` from each page
transactions.push(...page.items);
// Update the cursor to point to the next page
query.cursor = page.cursor.next;
// Continue until the server returns a null cursor
} while (query.cursor !== null);
Pending Transactions
Pending transactions are served from a separate endpoint, and contain less information than transactions that have been fully resolved. This is because NZ banks typically do not serve a consistent view of pending transactions (eg. the date and description often change). When working with pending transactions, it is recommended that you completely rebuild your local copy of this data (i.e. delete then re-create) each time you refresh it from this endpoint.
Conclusion
You should now be able to:
- Obtain recent user transactions
- Filter transactions by date
- Get transactions for a given account
Updated 4 months ago