Person Verify

Find out what you can do with our API...


API method to use: person_verify

Description


Validate your data against our UK people data sources.

This method can be used to validate and verify an individual using simple input parameters. If you can provide a name and address, we can search our vast dataset of 48+ million records and provide you with a match. You can then feel confident that you are dealing with a genuine customer who lives at the address they have provided.



This method is perfect for integration into ecommerce sites , particularly ones that sell age restricted items such as alcohol and pharmaceuticals or gaming sites. You may also want to check our https://t2a.io/methods/age_verificationage verification service.

Your data MUST contain:-

  • Surname
  • Forename / first initial
  • UK Postcode
  • UK Address (whole or partial)

The method will then attempt to locate the individual in our data. You can control the level of fuzziness that the method will use, by setting a series of parameters.

If a person is found in our data, the method returns a validation status true. We also describe the quality of the match.

If, for example, your data has a record for Ian Whitehead, and our method finds Ian Whithead (note the slight spelling difference) at the same address, we include this element:-

<match_code_surname>FUZZY</match_code_surname>

to indicate that there is a slight spelling difference.

Mandatory Parameters


None of the parameters are case sensitive apart from the api key or javascript key.

Name Description
api_key or javascript_key Use your API key if invoking server-side. If invoking from the browser via JavaScript, generate a JavaScript key using the javascript_key method.
surname The surname of the subject. The case is irrelevant.
forename The forename of the subject. If initial_match is set to true, this can be also be just the first letter.
postcode The postcode of the subject. Ideally this is the full UK postcode, but the method will check a partial code. If postcode_fuzzy is set to true, it will allow the final character of the postcode to be incorrect.

This can be in any case and any format

(such as YO98 9HZ or yo989HZ)
addr1 The first line of the address

Optional Parameters


Name Description
addr2 The second line of the address
addr3 The third line of the address
place The locality
town The postal town
surname_fuzzy Set to true (default) to allow a slight fuzzy match.
forename_fuzzy Set to true (default) to allow a slight fuzzy match.

Returned Values


The XML response is contained within a <person_verify_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code Returns the error code when the status is error. See below for error codes.
t2a_version_number The current API version number.
credit_used The number of credits used in order to execute the request.
validation_status Set to:-

NOT_FOUND when the person could not be validated.

FOUND when a person has been validated.

TOO_MANY when the search parameters indicates more than one person sharing the full name.
match_code_surname

Describes how we matched the surname. Possible values:-

  • FULL when the surname perfectly matched.
  • FUZZY when the surname was slightly incorrect (or a known synonym).
match_code_forename

Describes how we matched the forename. Possible values:-

  • FULL when the forename matched.
  • FUZZY when the forename was slightly incorrect or was a known synonym.
  • INITIAL when the forename was matched only by the first letter.
match_code_address

Describes how we matched the address. Possible values:-

  • FULL when the address input perfectly matched the person's address.
  • PARTIAL when the address input partially matched. This occurs if some (but not all) of the words in the address, place and town fields were matched, and they were in the correct order.
  • (None) when the address was not used when matching the person.

Error Codes


See the common error codes. There are no errors which are specific to this method.

Worked Example


Introduction
These examples are based around a fictitious record created for this documentation:-

Miss Angela Fanshawe

19 Snail Road

Heslingdown

York

YO98 9ZR

The person, address, postcode, telephone and place shown above do not exist; only the town, "York", is real, and the simulated postal code is similar to York area ones.

Perfect Match Example


Using these parameters to find our dummy record:-

Parameter Value
surname fanshawe
forename angela
postcode YO989ZR (or YO98 9ZR)
addr1 19 Snail Road
place heslingdown
town York

...returned the XML below. Note that the match codes are all FULL for the name and address values.


<?xml version="1.0"?>
<person_verify_res>
  <mode>normal</mode>
  <t2a_version_number>3.1.0.1</t2a_version_number>
  <validation_status>FOUND</validation_status>
  <match_code_forename>FULL</match_code_forename>
  <match_code_surname>FULL</match_code_surname>
  <match_code_address>FULL</match_code_address>
  <match_code_postcode>FULL</match_code_postcode>
</person_verify_res>

Fuzzy Match Example


Using these parameters to find our dummy record:-

Parameter Value
surname fanshaw
forename ANGELA
postcode YO989ZR
addr1 19 Snail

...returned the XML below. Note that the match code for the surname is FUZZY because of the slight spelling change, and PARTIAL for the address. You may optionally disable the fuzzy and partial matching.


<?xml version="1.0"?>
<person_verify_res>
  <mode>normal</mode>
  <t2a_version_number>2.2.3.8</t2a_version_number>
  <validation_status>FOUND</validation_status>
  <match_code_forename>FULL</match_code_forename>
  <match_code_surname>FUZZY</match_code_surname>
  <match_code_address>PARTIAL</match_code_address>
</person_verify_res>