The Account Model

The lowdown on how accounts are structured and what each key means.


This reference is intended for developers using Akahu's enduring account connectivity. Information provided may not be relevant for those using one-off account connectivity.

What is an Account?

At it's most basic, an Akahu account is something that has a balance. Some connections (like banks) have lots of accounts, while others (like KiwiSaver providers) may only have one. Different types of accounts have different attributes and abilities, which can get a bit confusing! The rest of this page should help you figure everything out, from an account's provider to whether it can make payments.

Keep in mind that we limit what information is available depending on your app permissions. This is done in order to protect user privacy, however it also means that some of the data here may not be visible to you.


The _id key is a unique identifier for the account in the Akahu system. It is always be prefixed by acc_ so that you can tell that it belongs to an account.


When you connect accounts to Akahu you have to log in to the account provider. Akahu keeps track of all of the accounts in that login session and gives them all a unique _credentials key, prefixed by creds_.

For example, if you have 3 ANZ accounts, they will all have the same _credentials. Your ANZ accounts and your friend's ANZ accounts have different login credentials, so they will have a different _credentials key. The _credentials key is in no way derived or related to your login credentials - it's just a random ID.


This tells you who the original account provider is (e.g. Demo Bank). It consists of:

  • name The name of the provider.
  • logo A URL pointing to an image of the provider's logo.
  • _id A unique identifier for this provider, prefixed by conn_.


This is the name of the account. If the connection allows customisation, the name will be the custom name (or nickname), e.g. "Spending Account". Otherwise Akahu falls back to the product name, e.g. "Super Saver".


This tells you whether Akahu can currently sign in to the account to refresh its data. It can be one of:

  • ACTIVE Akahu can sign in and refresh this account.

  • INACTIVE Akahu no longer has access to this account. This may be caused by the user revoking Akahu's access at the institution or changing their login credentials. When an account becomes INACTIVE your application should direct the the user back to the OAuth flow or to where they will be prompted to to re-establish this connection.


If the account has a well defined account number (eg. a bank account number, or credit card number) this will be defined here with a standard format across connections. This field will be the value undefined for accounts with KiwiSaver providers and investment platform accounts.

For NZ banks, we use the common format 00-0000-0000000-00.
For credit cards, we return a redacted card number 1234-****-****-1234 or ****-****-****-1234



Use at your own risk!

Akahu attempts to standardise this data as much as possible, however much of the time data is missing, different, or poorly specified between connections.

This is a less defined part of our API that lets us expose connection-specific data. An investment provider, for example, may expose a breakdown of investment results.

Some common keys include:

  • holder The account holder name as exposed by the provider. In the case of bank accounts this is the name on the bank statement.
  • payment_details If the account can be paid but is not a bank account (for example a KiwiSaver account), this field will have the following keys:
    • account_holder The recipient's name.
    • account_number The recipient's NZ bank account number.
    • particulars (Optional) Details required to be in the payment particulars.
    • code (Optional) Details required to be in the payment code.
    • reference (Optional) Details required to be in the payment reference.
    • minimum_amount (Optional) If there is a minimum amount in order to have the payment accepted, in dollars.
  • loan_details If the account is a loan, this will provide detailed information related to the loan, with the following keys:
    • purpose The purpose of the loan (E.g. HOME), if we can't determine the purpose, this will be UNKNOWN
    • type The type of loan (E.g. TABLE), if we can't determine the type, this will be UNKNOWN
    • interest Interest rate information for the loan.
      • rate The rate of interest
      • type The type of interest rate (E.g. FIXED)
      • expires_at When this interest rate expires, if available.
    • is_interest_only Is the loan currently in an interest only period?
    • interest_only_expires_at When the interest only period expires, if available.
    • term The duration/term of the loan for it to be paid to completion from the start date of the loan.
    • matures_at When the loan matures, if available.
    • initial_principal The loan initial principal amount, this was the original amount borrowed.
    • repayment Loan repayment information if available.
      • frequency The frequency of the loan repayment (E.g. MONTHLY).
      • next_date The next repayment date, if available.
      • next_amount The next instalment amount.
  • breakdown An investment breakdown. Details are passed straight through from integrations, making them very inconsistent.
  • portfolio An investment portfolio. Again, details are passed through from integrations, so some are missing various fields1.

1 A maximum of 200 funds/instruments are supported per investment account.


Akahu can refresh different parts of an account's data at different rates. The timestamps in the refreshed object tell you when that account data was last updated. When looking at a timestamp in here, you can think "Akahu's view of the account (balance/metadata/transactions) is up to date as of $TIME".

  • balance When the balance was last updated.
  • meta When other account metadata was last updated (any account property apart from balance).
  • transactions When we last checked for and processed any new transactions. This flag may be missing when an account has first connected, as it takes a few seconds for new transactions to be processed.
  • party When we last fetched identity data about the party who has authenticated with the financial institution when connecting this account. This data is updated by Akahu on a fixed 30 day interval, regardless of your app's data refresh configuration.


The account balance. Keys include:

  • current The current account balance. A negative balance indicates the amount owed to the account issuer. For example a checking account in overdraft will have a negative balance, same as the amount owed on a credit card or the principal remaining on a loan.
  • available (Optional) The balance that is currently available to the account holder.
  • limit (Optional) The credit limit for this account. For example a credit card limit or an overdraft limit. This value is only present when provided directly by the connected financial institution.
  • overdrawn (Optional) A boolean indicating whether this account is in overdraft.
  • currency The 3 letter ISO 4217 currency code that this balance is in (e.g. NZD).


What sort of account this is. Akahu provides specific bank account types, and falls back to more general types for other types of connection.

  • CHECKING An everyday spending account.
  • SAVINGS A savings account.
  • CREDITCARD A credit card.
  • LOAN A loan account.
  • KIWISAVER A KiwiSaver investment product.
  • INVESTMENT A general investment product.
  • TERMDEPOSIT A term deposit.
  • FOREIGN An account holding a foreign currency.
  • TAX An account with tax authorities.
  • REWARDS An account for rewards points, e.g. Fly Buys or True Rewards.
  • WALLET Available cash for investment or withdrawal from an investment provider.


The SAVINGS is not necessarily a regular bank account. It might not have transactions associated, or be able to receive payments.

Check the attributes field to see what this account can do.


The list of attributes indicates what abilities an account has. A list that can contain:

  • "TRANSACTIONS" This account has transactions and supports fetching them via Akahu.
  • "TRANSFER_TO" This account can receive transfers from accounts belonging to the same set of credentials.
  • "TRANSFER_FROM" This account can initiate transfers to accounts belonging to the same set of credentials.
  • "PAYMENT_TO" This account can receive payments from any Akahu account with the "PAYMENT_FROM" attribute.
  • "PAYMENT_FROM" This account can initiate payments to any Akahu account with the "PAYMENT_TO" attribute.