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.
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.
loan_detailsIf the account is a loan, this will provide detailed information related to the loan, with the following keys:
purposeThe purpose of the loan (E.g.
HOME), if we can't determine the purpose, this will be
typeThe type of loan (E.g.
TABLE), if we can't determine the type, this will be
interestInterest rate information for the loan.
rateThe rate of interest
typeThe type of interest rate (E.g.
expires_atWhen this interest rate expires, if available.
is_interest_onlyIs the loan currently in an interest only period?
interest_only_expires_atWhen the interest only period expires, if available.
termThe duration/term of the loan for it to be paid to completion from the start date of the loan.
matures_atWhen the loan matures, if available.
initial_principalThe loan initial principal amount, this was the original amount borrowed.
repaymentLoan repayment information if available.
frequencyThe frequency of the loan repayment (E.g.
next_dateThe next repayment date, if available.
next_amountThe next instalment amount.
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.
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.
partyWhen 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:
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.
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.
currencyThe 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.
CHECKINGAn everyday spending account.
SAVINGSA savings account.
CREDITCARDA credit card.
LOANA loan account.
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.
SAVINGSis not necessarily a regular bank account. It might not have transactions associated, or be able to receive payments.
attributesfield 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"This account can initiate payments to any Akahu account with the
Updated 3 months ago