One-Off Verify Name

📘

This guide is not applicable to Personal Apps. You must have a full app with identity permissions to follow this guide.

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 returned in the /identity/{id} response. To speed up development and reduce matching errors, we provide a POST identity/{id}/verify/name endpoint, allowing you do do this verification without the need to implement your own name matching logic.

Prerequisites

Before we begin, you will need to:

• Complete the One-Off Identity Verification guide
• Have the _id value of a successful One-Off Identity Result
• Have your Akahu App ID Token and App Secret.

Making the request

API Reference

To match a name against a identity result, make a POST request to the /identity/{id}/verify/name endpoint, with the following details in the body:

{
  // required
  "family_name": "Simpson",
  // optional
  "given_name": "Homer",
  // optional
  // If the user has multiple middle names separate them with a space
  "middle_name": "Jay",
}

The response will look like:

{
    "success": true,
    "item": {
        "sources": [
            {
                "type": "HOLDER_NAME",
                "match_result": "PARTIAL_MATCH", // Match result is a "PARTIAL_MATCH" since the holder did not contain the supplied middle name. If middle name was omitted from the request body this would return a "MATCH".
                "meta": {
                  // The Account Object from the identity Response
                  "name": "Regular Account",
                  "holder": "Mr. Homer J Simpson",
                  "account_number": "03-0481-0028919-00",
                  "address": "17 Tannock Place, Māngere East, Auckland, 2024",
                  "bank": "Demo Bank"
                  // ... and other fields, omitted for brevity
                },
                "verification": {
                    "family_name": true,
                    "middle_name": false,
                    "given_name": true,
                    "middle_initial": true,
                    "given_initial": false
                }
            },
            {
                "type": "PARTY_NAME",
                "match_result": "MATCH",
                "meta": {
                    // The Party Object from the identity response
                    "initials": [
                        "H J"
                    ],
                    "given_name": "Homer",
                    "middle_name": "Jay",
                    "family_name": "Simpson",
                    "full_name": "Homer Jay Simpson",
                    "prefix": "MR",
                    "gender": "MALE"

                },
                "verification": {
                    "family_name": true,
                    "middle_name": true,
                    "given_name": true,
                    "middle_initial": true,
                    "given_initial": true
                }
            }
        ],
        // the input parameters
        "name": {
          "family_name": "Simpson",
          "given_name": "Homer",
          "middle_name": "Jay",
        }
      }
}

Persistence

The identity verification endpoint is a non-persistent endpoint, meaning the results of a name verification are not stored as an entity within Akahu. The results are up to the calling app to process and store. This endpoint can only be used for up to 30 days for an Identity Result after completing the One-Off identity verification flow. See the One-Off Identity Verification guide for more details about data retention.

Verification sources

Akahu will verify name against two different verification sources, if they are available. These can be found within the type key in the source object.

It is up to the connecting app to check against their own requirements about which type of verification sources they can use.

For example, a investment provider that wishes to check a bank account is held in the name of a user before allowing a withdrawal will only look at the HOLDER_NAME type. Where as a app that just wants to verify a users identity may be able to use either HOLDER_NAME or PARTY_NAME types.

Successful match

Successful matches will return a object within the sources array. A successful match is defined as a minimum of the family_name being able to be matched against a verification source. To check for successful verification there are two status available from the match_result key.

Failed match

Failed matches do not return an object within the sources array. A match is failed if the family_name is not able to be matched against the verification source. A name that is unable to match against any verification source will return a empty sources array.