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 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
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:
nameThe name of the provider.
logoA URL pointing to an image of the provider's logo.
_idA unique identifier for this provider, prefixed by
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:
ACTIVEAkahu can sign in and refresh this account.
INACTIVEAkahu 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
INACTIVEyour 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.
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
For credit cards, we return a redacted card number
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:
holderThe account holder name as exposed by the provider. In the case of bank accounts this is the name on the bank statement.
addressThe account holder's address.
payment_detailsIf the account can be paid but is not a bank account (for example a KiwiSaver account), this field will have the following keys:
account_holderThe recipient's name.
account_numberThe 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.
breakdownAn investment breakdown. Details are passed straight through from integrations, making them very inconsistent.
portfolioAn investment portfolio. Again, details are passed through from integrations, so some are missing various fields1.
icpFor electricity providers, the account's ICP number.
usageFor 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.
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
balanceWhen the balance was last updated.
metaWhen other account metadata was last updated (any account property apart from balance).
transactionsWhen 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.
The account balance. Keys include:
currentThe 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.
currencyThe 3 letter ISO 4217 currency code that this balance is in (e.g. NZD).
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"This account can initiate payments to any Akahu account with the
If this account is a NZ bank account, Akahu will provide details of the account's bank branch (where it was opened). Details include:
nameThe branch name.
descriptionThe branch description.
phoneThe branch phone number.
addressThe branch address, consisting of:
line1The first address line.
line2The second address line.
cityThe city the branch resides in.
postcodeThe postcode the branch resides in.
countryThe country the branch resides in.
What sort of account this is. Akahu provides specific bank account types, and falls back to more general types for other types of connection.
CHECKINGAn everyday spending account.
SAVINGSA savings account.
CREDITCARDA credit card.
LOANA loan of some sort (used when we can't get a more specific type).
LOAN_PERSONALA personal loan.
LOAN_HOMEA home loan.
LOAN_BUSINESSA business loan.
KIWISAVERA KiwiSaver investment product.
INVESTMENTA general investment product.
TERMDEPOSITA term deposit.
FOREIGNAn account holding a foreign currency.
TAXAn account with tax authorities.
REWARDSAn account for rewards points, e.g. Fly Buys or True Rewards.
WALLETAvailable cash for investment or withdrawal from an investment provider.
Updated 4 days ago