ℹ️

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.

_migrated

The identifier of this account's predecessor.

This attribute is only present if the account has been migrated to an official open banking connection from a classic Akahu connection.

Read more about official open banking, and migrating to it here.

_authorisation

Financial accounts are connected to Akahu via an authorisation with the user's financial institution. Multiple accounts can be connected during a single authorisation, causing them to have the same authorisation identifier. This identifier can also be used to link a specific account to identity data for the party who completed the authorisation.

This identifier can also be used to revoke access to all the accounts connected to that authorisation.

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

_credentials (deprecated)

Deprecated: Please use _authorisation instead.

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

• connection_type The type of integration used to connect to this institution.

  This will be one of:

  • classic A classic Akahu connection, which uses Akahu's custom built integration to connect to the institution.
  • official An official open banking connection, which uses the institution's official open banking APIs.

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 attribute indicates the status of Akahu's connection to this account.

It is possible for Akahu to lose the ability to authenticate with a financial institution if the user revokes Akahu's access directly via their institution, or changes their login credentials, which in some cases can cause our long-lived access to be revoked.

The account status will be one of:

• ACTIVE Akahu can authenticate with the institution to retrieve data and/or initiate payments for this account.

• INACTIVE Akahu no longer has access to this account. Your application will still be able to access Akahu's cached copy of data for this account, but this will no longer be updated by refreshes. Write actions such as payments or transfers will no longer be available. Once an account is assigned the INACTIVE status, it will stay this way until the user re-establishes the connection. When your application observes an account with a status of INACTIVE, the user should be directed back to the Akahu OAuth flow or to https://my.akahu.nz/connections where they will be prompted to re-establish the connection.

formatted_account

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

meta

⚠️

Akahu standardises this metadata as much as possible. However depending on the specific integration and account, some data fields may be unavailable or poorly specified. Treat all fields in the meta object as optional.

This is a less defined part of our API that lets us expose data that may be specific to certain account types or financial institutions. 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.
• has_unlisted_holders Indicates if the account has other holders that are not listed in the holder field. This only applies to official open banking connections where the institution indicates a joint account, but only provides the authorising party's name.
• 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 Includes detailed information related to a loan account (if available from the loan provider):
  • 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 fields¹.

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

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

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

attributes

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

• "TRANSACTIONS" Akahu can fetch available transactions from this account.
• "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 another bank account.
• "PAYMENT_FROM" This account can initiate payments to another bank account.