VerifyNameResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-verify-name-result-schema.json",
  "title": "VerifyNameResult",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-identity-api-openapi.yml#/components/schemas/VerifyNameResult",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "enum": [
            true
          ]
        },
        "item": {
          "type": "object",
          "properties": {
            "sources": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/VerifyNameSource"
              }
            },
            "name": {
              "$ref": "#/$defs/VerifyNameData"
            }
          },
          "required": [
            "sources",
            "name"
          ]
        }
      },
      "required": [
        "success",
        "item"
      ]
    },
    {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "enum": [
            false
          ]
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "success"
      ]
    }
  ],
  "$defs": {
    "AccountId": {
      "type": "string",
      "format": "cuid",
      "pattern": "^acc_[a-z0-9]{25,27}$",
      "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."
    },
    "ConnectionId": {
      "type": "string",
      "format": "cuid",
      "pattern": "^conn_[a-z0-9]{25,27}$",
      "description": "The connected financial institution's unique identifier. This will always be prefixed with `conn_`."
    },
    "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"
      ]
    },
    "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": "#/$defs/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."
            }
          },
          "required": [
            "_id",
            "name",
            "holder"
          ],
          "description": "The Account data that this name was verified against"
        },
        "match_result": {
          "$ref": "#/$defs/VerifyNameMatchType"
        },
        "verification": {
          "$ref": "#/$defs/VerifyNameMatchedComponents"
        }
      },
      "required": [
        "type",
        "meta",
        "match_result",
        "verification"
      ]
    },
    "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"
    },
    "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": "#/$defs/ConnectionId"
              },
              "description": "The connections with this name"
            }
          },
          "required": [
            "value",
            "sources"
          ],
          "description": "The Party data that this name was verified against"
        },
        "match_result": {
          "$ref": "#/$defs/VerifyNameMatchType"
        },
        "verification": {
          "$ref": "#/$defs/VerifyNameMatchedComponents"
        }
      },
      "required": [
        "type",
        "meta",
        "match_result",
        "verification"
      ]
    },
    "VerifyNameSource": {
      "oneOf": [
        {
          "$ref": "#/$defs/VerifyNamePartySource"
        },
        {
          "$ref": "#/$defs/VerifyNameHolderSource"
        }
      ]
    }
  }
}