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
_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
_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
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 byconn_
.
name
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
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 theINACTIVE
status, it will stay this way until the user re-establishes the connection. When your application observes an account with a status ofINACTIVE
, 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
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
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.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 beUNKNOWN
type
The type of loan (E.g.TABLE
), if we can't determine the type, this will beUNKNOWN
interest
Interest rate information for the loan.rate
The rate of interesttype
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.
refreshed
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
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
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
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.
Updated 4 months ago