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

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

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

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