Guides

Key concepts

Learn about important concepts for working with the Akahu Apply API

Suggest Edits

Applications

The core function of Akahu Apply is to provide insights over a dataset consisting of financial accounts and their transactions. An Akahu Apply Application represents a container where financial data can be imported, processed, and prepared for analysis.

For example, if you are using Akahu Apply as part of a lending workflow, a new Application should be set up in Akahu Apply for each lending application that you wish to process.

Resources

Financial data is added to an Application via one or more Resources. The data from multiple resources is compiled into a single aggregate dataset by generating a Report.

A Resource is a high level concept that can represents a number of concrete sources of financial data. Akahu Apply currently supports the following resource types:

Documents

One or more Documents can be uploaded to an Application as a way to import financial data for analysis.

A document represents a single PDF file containing financial statements that are relevant to the application.

When a document is uploaded to an Application, Akahu Apply will process the information from the document using text extraction and OCR methods, then convert it to a standardised format.

Akahu Apply can process PDF documents containing multiple financial statements, and documents with additional pages.

ℹ️

Currently, Documents can only be added to an Application via Sharing Request. Direct document upload via API will be available shortly.

Open Banking Connections

Financial data can be imported into an application using an Akahu one-off open banking connection. This connection is facilitated as part of the Sharing Request flow.

Open Banking Connections allow the applicant to contribute data to an Application by consenting to data sharing and connecting their financial accounts via Akahu. The relevant financial data is collected directly from the applicant's financial institution and automatically added to the Application dataset.

Completion of an Open Banking Connection will also result in one or more Documents being automatically added to the Application, because PDF bank statements are collected as part of this process.

Open Banking Connections are the best method of applicant data collection due to the complete dataset that is provided. This reduces the risk of issues introduced by the applicant failing to supply a complete set of documents.

Sharing Requests

You can invite your applicant to provide financial data for their Application by creating a Sharing Request. Each Sharing Request is associated with a specific Application, and you can create multiple Sharing Requests per Application.

Using a Sharing Request, you can send your applicant to an Akahu Apply web page where they will be guided through the process of sharing the requested financial data. Any Resources created by the applicant during this process will automatically be attached to the associated Application. Akahu Apply supports two methods for applicant data sharing:

  • Manual upload of PDF bank statements.
  • Open Banking Connections flow.

The applicant can use a combination these two methods as needed to provide the full scope of requested data.

Sharing Requests can be customised with the following options:

  • Number of days of historic data requested (between 30 and 365).
  • Disable/enable manual document upload.

Sharing Requests created via API can also be created with a redirect URI. This should be a URI in your application that the user will be navigated to upon completion of the Sharing Request. If you do not supply a redirect URI, the user will be shown a generic success page and instructed to close the browser tab.

Reports

Once an Application has been populated with one or more data Resources, a Report can be created. A Report combines all of the data from the Application’s Resources into an aggregate, enriched dataset.

The compiled Report data can be accessed in JSON format via API for further analysis.

A human-friendly version of the report data can be downloaded as an interactive HTML file that can be viewed using a web browser.

Screenshot of an example HTML report

Accounts

Each financial account included in the Report dataset is represented by an Account record. If data relating to the same financial account is included in multiple Resources, the data will be combined (deduplicated) into a single Account record.

Each Account includes information such as the Account type (e.g. depository, loan, or credit card), the date periods for which transaction data is available for the account, opening and closing balances, and credit limits.

Below is an example account record:

{
  "_id": "report_acc_ra2se6ggwwhhro94x56tlaqy",
  "type": "DEPOSITORY",
  "identifier": "38-0000-0000000-00",
  "holder": "Mr Example Applicant",
  "periods": [
    {
      "_source": "src_jui8wiu2q15bom4b6yt25yxx",
      "opening_balance": 380.96,
      "closing_balance": 1053.02,
      "limit": null,
      "start": "2025-03-31T11:00:00.000Z",
      "end": "2025-06-29T12:00:00.000Z"
    }
  ],
  "provider": {
    "_id": "conn_cjgaac5at000001qi2yw8ftil",
    "name": "Kiwibank",
    "logo": "https://cdn.akahu.nz/logos/connections/conn_cjgaac5at000001qi2yw8ftil"
  }
}

Transactions

The flow of money in and out of each Account is described by Transactions.

Akahu Apply provides enriched transaction data with insights such as income and expense categorisation. Key indicators on transaction data highlight activity that is relevant for lending decisions, such as ATM withdrawals and dishonoured payments.

Interesting fields on each transaction include:

  • action - One of money_in, money_out, or transfer. This field describes the net flow of money in the context of all Accounts in the report dataset.
  • nzfcc - The New Zealand Financial Category Code (NZFCC) that has been assigned to the transaction by Akahu Apply. This is the most granular and flexible tier of categorisation provided by Akahu Apply. However due to the large number of NZFCCs, we recommend that you instead start with our income and spending categories, falling back to the underlying NZFCC only if necessary for your use-case.
  • income_category - The income category that Akahu Apply has assigned to the Transaction.
  • spending_category - The spending category that Akahu Apply has assigned to the Transaction.
  • merchant - If the Transaction is money_out and Akahu Apply has identified a merchant as the counterparty of the Transaction, this contains the details of the merchant such as their name and logo.

Below is an example of a transaction record:

{
  "_id": "report_trans_hlyt2oipojdbz8gteqtwmoi7",
  "_account": "report_acc_daqj6g4rjtprk1qzpjjv7wbi",
  "_source": "src_quawo2v7t625wlx8pch6in09",
  "action": "money_out",
  "type": "DEBIT",
  "date": "2025-05-10T12:00:00.000Z",
  "description": "MATAKANA LIQUOR CENT MATAKANA",
  "amount": -74.99,
  "balance": 1295.6,
  "merchant": {
    "_id": "merchant_cjtw6ueag0020s3ojfequ70zw",
    "name": "Liquor Centre",
    "logo": "https://cdn.akahu.nz/logos/merchants/merchant_cjtw6ueag0020s3ojfequ70zw"
  },
  "nzfcc": {
    "_id": "nzfcc_ckouvvyac001c08mlbyp5doni",
    "name": "Liquor stores"
  },
  "income_category": null,
  "spending_category": {
    "code": "spending:005/entertainment",
    "name": "Entertainment"
  }
}

Updated about 6 hours ago