--- updatedAt: 2026-04-22T22:43:18.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # [One-off access] Verify a name > ⚠️ > > **Authentication** > This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication. To verify your user's identity, you may wish to match the name that you have on file against an official record such as the bank account holder name or Party name, returned via the Identity Response. For more details about the data returned, see: - [📚 One-Off Verify Name](/docs/oneoff-verify-name) - [📖 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": { "IdentityRequestId": { "type": "string", "format": "cuid", "pattern": "^id_[a-z0-9]{25,27}$", "example": "id_c01234567890123456789012345", "description": "A unique Akahu identity identifier." }, "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 } } }, "VerifyNameData": { "type": "object", "properties": { "given_name": { "type": "string", "description": "The given name/first name to match against, if available" }, "middle_name": { "type": "string", "description": "The middle name to match against, if available" }, "family_name": { "type": "string", "description": "The family name/surname to match against" }, "initials": { "type": "array", "items": { "type": "string" }, "description": "An array of initials to match against, if available" } }, "required": [ "family_name" ], "example": { "given_name": "Homer", "middle_name": "Jay", "family_name": "Simpson" } }, "VerifyNameMatchType": { "type": "string", "enum": [ "MATCH", "PARTIAL_MATCH" ], "description": "What is the quality of the Match?\n - `MATCH` → All name components matched\n - `PARTIAL_MATCH` → Some of the name components matched, but not all" }, "VerifyNameMatchedComponents": { "type": "object", "properties": { "given_name": { "type": "boolean", "description": "Did the given name match?" }, "middle_name": { "type": "boolean", "description": "Did the middle name match?" }, "family_name": { "type": "boolean", "description": "Did the family name match?" }, "middle_initial": { "type": "boolean", "description": "Did the middle initial match? (E.g. [B, J] matching Homer J Simpson)" }, "given_initial": { "type": "boolean", "description": "Did the given initial match? (E.g. [H, A] matching Homer J Simpson)" } }, "required": [ "given_name", "middle_name", "family_name", "middle_initial", "given_initial" ], "description": "A collection of flags indicating which name components matched", "example": { "family_name": true, "middle_name": true, "given_name": true, "middle_initial": true, "given_initial": true } }, "OneOffIdentityParty": { "type": "object", "properties": { "given_name": { "type": "string" }, "middle_name": { "type": "string" }, "family_name": { "type": "string" }, "initials": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "string" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE", "UNKNOWN" ] } }, "description": "The Party data that this name was verified against" }, "OneOffVerifyNamePartySource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PARTY_NAME" ], "description": "The name was matched against a Party" }, "meta": { "$ref": "#/components/schemas/OneOffIdentityParty" }, "match_result": { "$ref": "#/components/schemas/VerifyNameMatchType" }, "verification": { "$ref": "#/components/schemas/VerifyNameMatchedComponents" } }, "required": [ "type", "meta", "match_result", "verification" ], "example": { "type": "PARTY_NAME", "match_result": "MATCH", "meta": { "initials": [ "H", "J" ], "given_name": "Homer", "middle_name": "Jay", "family_name": "Simpson", "prefix": "MR", "gender": "MALE" }, "verification": { "family_name": true, "middle_name": true, "given_name": true, "middle_initial": true, "given_initial": true } } }, "OneOffVerifyNameHolderSource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "HOLDER_NAME" ], "description": "The name was matched against an Account Holder" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/OneOffIdentityAccount" }, { "description": "The Account data that this name was verified against" } ] }, "match_result": { "$ref": "#/components/schemas/VerifyNameMatchType" }, "verification": { "$ref": "#/components/schemas/VerifyNameMatchedComponents" } }, "required": [ "type", "meta", "match_result", "verification" ], "example": { "type": "HOLDER_NAME", "match_result": "PARTIAL_MATCH", "meta": { "name": "Regular Account", "holder": "Mr. Homer J Simpson", "has_unlisted_holders": false, "account_number": "03-0481-0028919-00", "bank": "Demo Bank" }, "verification": { "family_name": true, "middle_name": false, "given_name": true, "middle_initial": true, "given_initial": false } } }, "OneOffVerifyNameSource": { "oneOf": [ { "$ref": "#/components/schemas/OneOffVerifyNamePartySource" }, { "$ref": "#/components/schemas/OneOffVerifyNameHolderSource" } ], "discriminator": { "propertyName": "type", "mapping": { "PARTY_NAME": "#/components/schemas/OneOffVerifyNamePartySource", "HOLDER_NAME": "#/components/schemas/OneOffVerifyNameHolderSource" } } }, "OneOffVerifyNameResult": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "item": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/OneOffVerifyNameSource" } }, "name": { "$ref": "#/components/schemas/VerifyNameData" } }, "required": [ "sources", "name" ] } }, "required": [ "success", "item" ] }, { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" } }, "required": [ "success" ] } ] } } }, "tags": [ { "name": "Identity" } ], "paths": { "/identity/{id}/verify/name": { "post": { "tags": [ "Identity" ], "summary": "[One-off access] Verify a name", "description": "> ⚠️\n>\n> **Authentication**\n> This endpoint requires [app-scoped](/reference/api-akahu-io-authentication#app-scoped-endpoints) authentication.\n\nTo verify your user's identity, you may wish to match the name that you have on file against an official record such as the bank account holder name or Party name, returned via the Identity Response.\n\nFor more details about the data returned, see:\n - [📚 One-Off Verify Name](/docs/oneoff-verify-name)\n - [📖 Identity model](/docs/the-oneoff-identity-result-model)", "security": [ { "app_auth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/IdentityRequestId" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyNameData" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneOffVerifyNameResult" } } } }, "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" } } } } } } ```