--- updatedAt: 2026-04-22T22:43:18.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # [One-off access] Get identity result > ⚠️ > > **Authentication** > This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication. Get the results of an Identity OAuth result using the authorization `code` provided upon redirection to your `redirect_uri` after the user's successful completion of the authorisation flow. This can be used to verify a user's identity using the data that is held about them by their financial institution. For more information about our Identity OAuth flow see our: - [📚 One-off Identity guide](/docs/oneoff-identity-verification) - [📚 Identity verification guide](/docs/identity-verification) - [📖 Identity model](/docs/the-oneoff-identity-result-model) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Akahu Enduring API", "description": "This API is the primary way for apps to interact with a user's data.", "version": "1.0.0" }, "servers": [ { "url": "https://api.akahu.io/v1" } ], "components": { "securitySchemes": { "app_auth": { "type": "http", "scheme": "basic", "description": "App-level Authentication:\n\nHTTP Basic Auth with the username being your **App ID Token** and the password being your **App Secret**.\n> `Basic {app_token}:{app_secret}`\n\nThis will allow you to act as your Akahu **application**, rather than as a specific user." } }, "responses": { "400": { "description": "Your request was malformed or otherwise unacceptable. More details are provided under the `message` key in the response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Content-Type" } } } } } }, "401": { "description": "You are not authorised to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Permission Denied" } } } } } }, "403": { "description": "You are not allowed to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden" } } } } } }, "404": { "description": "The item you are trying to access doesn't exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Not Found" } } } } } }, "500": { "description": "An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong" } } } } } } }, "schemas": { "ConnectionId": { "type": "string", "format": "cuid", "pattern": "^conn_[a-z0-9]{25,27}$", "example": "conn_cjgaac5at000001qi2yw8ftil", "description": "The connected financial institution's unique identifier. This will always be prefixed with `conn_`." }, "IdentityRequestId": { "type": "string", "format": "cuid", "pattern": "^id_[a-z0-9]{25,27}$", "example": "id_c01234567890123456789012345", "description": "A unique Akahu identity identifier." }, "ConnectionType": { "type": "string", "description": "The type of integration used to connect to this institution.\n\nThis will be one of:\n- `classic` A classic Akahu connection, which uses Akahu's custom built integration to connect to the institution.\n- `official` An official open banking connection, which uses the institution's official open banking APIs.", "enum": [ "classic", "official" ], "example": "official" }, "ConnectionInfo": { "type": "object", "description": "Information about the financial institution where the account is held (eg. ANZ bank).", "properties": { "_id": { "$ref": "#/components/schemas/ConnectionId" }, "name": { "type": "string", "description": "Display name for the connected institution.", "example": "My Bank" }, "logo": { "type": "string", "format": "uri", "description": "A URL pointing to an image of the institution's logo.", "example": "https://cdn.akahu.nz/logos/connections/conn_cjgaac5at000001qi2yw8ftil" }, "connection_type": { "$ref": "#/components/schemas/ConnectionType" } }, "required": [ "_id", "name", "logo", "connection_type" ] }, "OneOffIdentityAccount": { "type": "object", "description": "Identity Account", "properties": { "bank": { "type": "string", "description": "Display name of the bank", "example": "Kiwibank" }, "account_number": { "type": "string", "description": "Unique bank account identifer", "example": "38-9009-0000000-00" }, "holder": { "type": "string", "description": "Names of the owner of the account", "example": "F BAGGINS" }, "has_unlisted_holders": { "type": "boolean", "description": "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.", "example": false } } }, "Identities": { "type": "object", "description": "Identity information derived from a user's connected accounts.", "properties": { "name": { "type": "string", "description": "Name of one of the account holders.", "example": "F BAGGINS" }, "formatted_account": { "type": "string", "description": "Bank account number of the account this holder was derived from.", "example": "38-9009-0000000-00" }, "meta": { "type": "object", "description": "Currently reserved for future use to house additional metadata about the user.", "example": {} } } }, "AddressComponents": { "type": "object", "description": "Breakdown of the parts that make up this address.", "properties": { "street": { "type": "string", "description": "Street name from the address", "example": "27 Bag End" }, "suburb": { "type": "string", "description": "Suburb name from the address", "example": "Bagshot Row" }, "city": { "type": "string", "description": "City name from the address", "example": "Hobbiton" }, "region": { "type": "string", "description": "Region name from the address", "example": "Hobbiton" }, "postal_code": { "type": "string", "description": "Postal code from the address", "example": 1011 }, "country": { "type": "string", "description": "Country from the address", "example": "Middle Earth" } } }, "AddressType": { "type": "string", "example": "RESIDENTIAL", "enum": [ "RESIDENTIAL", "POSTAL", "UNKNOWN" ], "description": "Type of address:\n\n- `RESIDENTIAL` → Where the user lives.\n\n- `POSTAL` → Where the user can be reached by mail such as a PO-BOX.\n\n- `UNKNOWN` → Akahu was unable to determine which of the two types of address this is." }, "Addresses": { "type": "object", "description": "Address derived from a user's connected accounts.", "properties": { "type": { "$ref": "#/components/schemas/AddressType" }, "value": { "type": "string", "description": "The raw address value provided by the bank.", "example": "27 Bag End, Bagshot Row, Hobbiton, 1011" }, "formatted_address": { "type": "string", "description": "Optional parsed and formatted address string.", "example": "27 Bag End, Bagshot Row, Hobbiton, Middle Earth, 1011" }, "place_id": { "type": "string", "description": "Google Places identifier from [Google Places API](https://developers.google.com/maps/documentation/places/web-service/overview).", "example": "xxxxxxxxxxxxxxxxxxxxxxxxx" }, "components": { "$ref": "#/components/schemas/AddressComponents", "description": "Breakdown of the parts that make up this address." } } }, "OneOffIdentity": { "type": "object", "description": "One of Identity [Model](/docs/the-oneoff-identity-result-model)", "properties": { "_id": { "$ref": "#/components/schemas/IdentityRequestId" }, "status": { "type": "string", "example": "PROCESSING", "enum": [ "PROCESSING", "COMPLETE", "ERROR" ], "description": "- `PROCESSING` → Identity request is in progress, continue to poll for a final state of `COMPLETE` or `ERROR`.\n\n- `COMPLETE` → Final success status reached and identity data has been returned.\n\n- `ERROR` → Final error status reached due to a fatal error occurred during processing.\n\nFor more details about one of identity statuses see:\n - [📖 Identity Status reference](/docs/the-oneoff-identity-result-model#identity-status)" }, "source": { "description": "The source / connection that provided the identity data.", "$ref": "#/components/schemas/ConnectionInfo" }, "accounts": { "type": "array", "description": "Identity information registered on linked accounts", "items": { "$ref": "#/components/schemas/OneOffIdentityAccount" } }, "identities": { "type": "array", "description": "List of identity information derived from a user's connected accounts.", "items": { "$ref": "#/components/schemas/Identities" } }, "addresses": { "type": "array", "description": "List of addresses derived from a user's connected accounts.", "items": { "$ref": "#/components/schemas/Addresses" } } } } } }, "tags": [ { "name": "Identity" } ], "paths": { "/identity/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The authorization `code` received from the identity OAuth redirect.", "schema": { "type": "string" } } ], "get": { "tags": [ "Identity" ], "summary": "[One-off access] Get identity result", "security": [ { "app_auth": [] } ], "description": "> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nGet the results of an Identity OAuth result using the authorization `code` provided upon redirection to your `redirect_uri` after the user's successful completion of the authorisation flow.\n\nThis can be used to verify a user's identity using the data that is held about them by their financial institution.\n\nFor more information about our Identity OAuth flow see our:\n - [📚 One-off Identity guide](/docs/oneoff-identity-verification)\n - [📚 Identity verification guide](/docs/identity-verification)\n - [📖 Identity model](/docs/the-oneoff-identity-result-model)", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/OneOffIdentity" } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "500": { "$ref": "#/components/responses/500" } } } } } } ```