ℹ️

This page relates to our Oneoff Identity Verification flow.

Identity Status

Identity requests go through a series of statuses as we prepare the data for you. These statuses are:

• PROCESSING: We are still working on this request. You should keep polling this endpoint until it switches to either COMPLETE or ERROR.
• COMPLETE: You can now view the result (as described by the rest of this page). Once this status has been reached, it will not change again, so polling should halt.
• ERROR: A fatal error occurred during processing. Once this status has been reached, it will not change again, so polling should halt.

Typically requests will go directly from PROCESSING to COMPLETE, taking around 1-2 seconds.

The Identity Result

If the status is COMPLETE, the response will contain the identity data that was requested.

_id

The _id key is a unique identifier for the identity request in the Akahu system. It is always be prefixed by id_.

status

As described above, the status of the identity request.

created_at

An ISO 8601 timestamp of when this identity request was created.

updated_at

An ISO 8601 timestamp of when this identity request was last updated.

expires_at

An ISO 8601 timestamp of when access to this identity request will expire. At this point all identity-related data will no longer be accessible to you, and will be deleted according to our privacy policy. Typically this is 29 days after the status reaches COMPLETE.

identities

Should you have permission to view identity data, a list of Identity Items.

addresses

Should you have permission to view address data, a list of Address Items.

accounts

Should you have permission to view account data, a list of Account Items.

source

The source that provided this data. This is supplied as an object with the following keys:

• _id A unique ID for this source. This will always begin with conn_, and will be an Akahu Connection ID (that is, it will be returned by this API endpoint).
• name The name of this source.
• logo A logo for this source.

profile

Only present if you are using Akahu's Oauth profile feature (typically used by identity verification providers).

This entry describes the profile used when retrieving the data. It has the following keys:

• _id The ID of this profile. Will always begin with profile_.
• name The name of this profile.

errors

If present, a list of non-fatal errors that have occured with this identity request. If data that should be present is missing from the result, the explanation may be supplied in this property.

Identity Data

If you have the required permissions, you will receive an array of Identity items under the identities key in the result item. This data is derived from the Account Data.

Each Identity item will have the following properties:

name

The name of one of the account holders.

formatted_account

The NZ bank account number of the account this holder was derived from, in the standard format 00-0000-0000000-00.
This will always match the account_number property in the Account Data.

meta

Reserved for future use, this is currently an empty object.

Address Data

If you have the required permissions, you will receive an array of Address items under the addresses key in the result item. This data is derived from the Account Data.

Each Address item will have the following properties:

type

The type of address this is. Will be one of:

• RESIDENTIAL This address is where the user lives.
• POSTAL This address is where the user can be reached by mail.
• UNKNOWN Akahu was unable to determine which of the two types of address this is.

value

The raw address value provided by the bank.

formatted_address

A parsed and formatted address string. This may not be present, or may be null, if the raw value is poorly formed.

place_id

The place ID according to the Google Places API. This may not be present, or may be null, if the raw value is poorly formed.

components

A breakdown of the parts that make up this address. This may not be present, or may be null, if the raw value is poorly formed. If present, will be an object with the following keys:

• street
• suburb
• city
• region
• postal_code
• country

Account Data

If you have the required permissions, you will receive an array of Account items under the accounts key in the result item.

Each Account item will have the following properties:

name

The name is the name of the account. If available this will be the nickname the user has set for the account (like "Spending"), otherwise it will be the product name (like "Everyday").

account_number

The NZ bank account number for this account, in the standard format 00-0000-0000000-00.
For accounts that do not have NZ bank account numbers, such as credit cards, it will be a less well-defined string, depending on what the bank provides (such as ****-****-****-0000).

holder

The account holder name, exactly as displayed by the bank.

address

This field may or may not be present, depending on availablity of the underlying data.

If present it will be a string of the address associated with the account, exactly as displayed by the bank.

bank

The name of the bank that this data comes from. Intended for display purposes, for programmatic purposes prefer the top-level source attribute, which provides a unique ID.

branch

If this data is available, the bank branch to which this account belongs. If present, this will be an object with the keys:

• _id A unique Akahu ID for this bank branch. It will always begin with bank_branch_.
• description The descriptive name of this bank branch.
• phone An E.164 formatted phone number for this bank branch.
• address An object containing the address of this bank branch, consisting of the keys:
  • line1 The first address line.
  • line2 The second address line (optional).
  • line3 The third address line (optional).
  • city The city of this branch.
  • country The country of this branch (will always be "New Zealand", as those are the only branches supported by Akahu).
  • postcode The postcode of this branch.