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.

_id

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.

_credentials

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.

connection

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_.

name

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".

status

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 my.akahu.io where they will be prompted to to re-establish this connection.

formatted_account

If the account has a well defined account number (e.g. a bank account number) this will be defined here with a standard format across connections.

For NZ banks, we use the common format 00-0000-0000000-00.

meta

⚠️

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.
  • address The account holder's address.
  • 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.
  • 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.
  • icp For electricity providers, the account's ICP number.
  • usage For internet and mobile providers, the current usage and limits for internet, data, minutes, and SMS.

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

refreshed

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.

balance

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.
  • 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).

attributes

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.

branch

If this account is a NZ bank account, Akahu will provide details of the account's bank branch (where it was opened). Details include:

  • name The branch name.
  • description The branch description.
  • phone The branch phone number.
  • address The branch address, consisting of:
    • line1 The first address line.
    • line2 The second address line.
    • city The city the branch resides in.
    • postcode The postcode the branch resides in.
    • country The country the branch resides in.

type

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 of some sort (used when we can't get a more specific type).
  • LOAN_PERSONAL A personal loan.
  • LOAN_HOME A home loan.
  • LOAN_BUSINESS A business loan.
  • KIWISAVER A KiwiSaver investment product.
  • INVESTMENT A general investment product.
  • TERMDEPOSIT A term deposit.
  • FOREIGN An account holding a foreign currency.
  • TELCO An account with a telco provider.
  • ISP An account with an internet provider.
  • POWER An account with a electricity provider.
  • GAS An account with a gas provider.
  • POWER_GAS An account with an electricity and gas provider.
  • TRANSPORT An account with a transport provider.
  • ENTERTAINMENT An account with an entertainment provider.
  • TAX An account with tax authorities.