Enduring 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 /accounts response. To speed up development and reduce matching errors, we provide a POST /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:

• To be able to make requests to the Akahu API (see here for instructions).
• A user access token (<<apiKey>>). Follow the Getting Started Guide to obtain one.
• Your app access token (<<appToken>>). You should get this when you create your app.
• An Akahu account with at least one institution connected. To get a HOLDER_NAME result an account must be shared with the app too.

Making the request

API Reference

To match a name, make a POST request to the /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": "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
                }
            },
            {
                "type": "HOLDER_NAME",
                "meta": {
                    "_id": "acc_ckuror24i000309l4z227e132",
                    "name": "Regular Account",
                    "formatted_account": "03-0481-0028919-00",
                    "holder": "MR H J SIMPSON"
                },
                "match_result": "PARTIAL_MATCH",
                "verification": {
                    "family_name": true,
                    "middle_name": false,
                    "given_name": false,
                    "middle_initial": true,
                    "given_initial": true
                }
            },
        ],
        // the input parameters
        "name": {
          "family_name": "Simpson",
          "given_name": "Homer",
          "middle_name": "Jay",
        }
      }
}

Matching against a specific account

To match a name against a specific account, make a POST request to /verify/name/{_account}, where _account is the account id. This will only return sources where HOLDER_NAME will match against the specific account and PARTY_NAME will only match against the party details associated with the account.

Persistence

The verify name 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.

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.