Enduring Verify Name
Learn how to verify names using Akahu's enduring access flow.
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
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.
Type | Description |
---|---|
HOLDER_NAME | Account holder name. This is the legal holder of that account, so in the case of joint accounts it will contain multiple names. This is provided as-is from the connected institution. |
PARTY_NAME | This is the name that the connected institution associates with the credentials that the user entered. It will always belong to a single person, business, or trust. |
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.
Match Result | Description |
---|---|
MATCH | All supplied request parameters match against the verification source |
PARTIAL_MATCH | There is a match on family_name but no match on other supplied request parameters. |
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.
Updated 4 months ago