---
updatedAt: 2026-04-22T22:43:18.000Z
agentTools:
  projectIndex: https://developers.akahu.nz/llms.txt
---

# [Enduring access] Verify a name

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.

This will match against all available sources from all accounts that the user has connected to your app.

For more details about the data returned, see:
  - [📚 Enduring Verify Name](/docs/enduring-verify-name)

# 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": {
    "parameters": {
      "xAkahuId": {
        "name": "X-Akahu-Id",
        "in": "header",
        "required": true,
        "description": "Your **App ID Token**.",
        "schema": {
          "type": "string"
        },
        "example": "{{app_token}}"
      }
    },
    "securitySchemes": {
      "user_token": {
        "type": "http",
        "scheme": "bearer",
        "description": "User-level Authentication:\n\nHttp Bearer Auth with the token being a consented **User Access Token**.\n> `Bearer {user_token}`\n\nThis will allow you to act on a **user's** behalf when accessing the API."
      }
    },
    "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_`."
      },
      "AccountId": {
        "type": "string",
        "format": "cuid",
        "pattern": "^acc_[a-z0-9]{25,27}$",
        "example": "acc_c01234567890123456789012345",
        "description": "A unique identifier for the account in the Akahu system. It is always prefixed by `acc_` so that you can tell that it belongs to an account."
      },
      "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
        }
      },
      "VerifyNamePartySource": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "PARTY_NAME"
            ],
            "description": "The name was matched against a Party"
          },
          "meta": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "description": "The party name that was matched"
              },
              "sources": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ConnectionId"
                },
                "description": "The connections with this name"
              }
            },
            "required": [
              "value",
              "sources"
            ],
            "description": "The Party 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": "PARTY_NAME",
          "meta": {
            "value": "Mr. Homer Jay Simpson",
            "sources": [
              "conn_ckhe08hru0000b8x179gg2v73"
            ]
          },
          "match_result": "MATCH",
          "verification": {
            "family_name": true,
            "middle_name": true,
            "given_name": true,
            "middle_initial": false,
            "given_initial": false
          }
        }
      },
      "VerifyNameHolderSource": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "HOLDER_NAME"
            ],
            "description": "The name was matched against an Account Holder"
          },
          "meta": {
            "type": "object",
            "properties": {
              "_id": {
                "$ref": "#/components/schemas/AccountId"
              },
              "name": {
                "type": "string"
              },
              "formatted_account": {
                "type": "string"
              },
              "holder": {
                "type": "string"
              },
              "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
              }
            },
            "required": [
              "_id",
              "name",
              "holder"
            ],
            "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",
          "meta": {
            "_id": "acc_ckuror24i000309l4z227e132",
            "name": "Regular Account",
            "formatted_account": "03-0481-0028919-00",
            "holder": "MR H J SIMPSON",
            "has_unlisted_holders": false
          },
          "match_result": "PARTIAL_MATCH",
          "verification": {
            "family_name": true,
            "middle_name": false,
            "given_name": false,
            "middle_initial": true,
            "given_initial": true
          }
        }
      },
      "VerifyNameSource": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/VerifyNamePartySource"
          },
          {
            "$ref": "#/components/schemas/VerifyNameHolderSource"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "PARTY_NAME": "#/components/schemas/VerifyNamePartySource",
            "HOLDER_NAME": "#/components/schemas/VerifyNameHolderSource"
          }
        }
      },
      "VerifyNameResult": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "item": {
                "type": "object",
                "properties": {
                  "sources": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/VerifyNameSource"
                    }
                  },
                  "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": {
    "/verify/name": {
      "post": {
        "tags": [
          "Identity"
        ],
        "summary": "[Enduring access] Verify a name",
        "description": "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.\n\nThis will match against all available sources from all accounts that the user has connected to your app.\n\nFor more details about the data returned, see:\n  - [📚 Enduring Verify Name](/docs/enduring-verify-name)",
        "security": [
          {
            "user_token": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xAkahuId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyNameData"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyNameResult"
                }
              }
            }
          },
          "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"
          }
        }
      }
    }
  }
}
```