One-Off Verify Name
Learn how to verify names using Akahu's one-off 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 /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
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.
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 connection provider. |
PARTY_NAME | This is the name that the connection provider 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 3 months ago