Signup Login

Validate a Person

API Method: validate_person

Description

This method allows the validation of a UK person, by matching your supplied data to our people data.

Your data can contain:-

  • Surname (mandatory)
  • Forename / first initial (mandatory)
  • UK Postcode
  • UK Address (whole or partial)
  • Date of birth (DOB)
  • UK landline or mobile telephone number

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, the method returns the full name, address, date of birth and telephone numbers, together with information as to how the match was made.

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

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.

Optional Parameters

Name Description
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
addr2 The second line of the address
addr3 The third line of the address
place The locality
town The postal town
telephone_number The subject’s UK landline or mobile phone number.
dob_y The subject’s year of birth e.g. 1990. The dob_y parameter is only effective when dob_m is also specified.
dob_m The subject’s month of birth 1-12. The dob_m parameter is only effective when the dob_y parameter is also specified.
dob_d The day of birth 1-31

surname_fuzzy Set to true (default) to allow a slight fuzzy match.
forename_fuzzy Set to true (default) to allow a slight fuzzy match.
initial_match Set to true (default) to allow a forename match where ony the first letter matches.
postcode_partial Set to true (default) to allow a match where only the final character of the postcode is incorrect.
dob_partial Set to true (default) to allow a DOB match to ignore the day supplied, if a full DOB match cannot be found.

Returned Values

The XML response is contained within a <validate_person_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.
person A <person> record. This is only present when the method has validated a person.
validation_status Set to:-

NOT_FOUND when the person could not be validated.

FOUND when a person has been validated.

FOUND_UNLISTED when the person was only found in our unlisted telephone data. Licence (and data protection) restrictions prevent out giving any more information. There is no <person> instance when this occurs.
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.
  • (None) when the address was not used when matching the person.
match_code_postcode

Describes how we matched the postcode. Possible values:-

  • FULL when the supplied postcode perfectly matched the person’s postcode.
  • PARTIAL when the postcode input partially matched.
  • (None) when the postcode was not used when matching the person.
match_code_dob

Describes how we matched the date of birth. Possible values:-

  • FULL when the supplied DOB perfectly matched the person's DOB.
  • PARTIAL when the date and month matched.
  • (None) when the DOB was not used when matching the person.
match_code_tel

Describes how we matched the telephone. Possible values:-

  • FULL when the supplied telephone number perfectly matched the person's landline or mobile number.
  • (None) when the telephone 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

Telephone: 07921 000000

Born: 22nd February 1991

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. Note also that the DOB and telephone numbers were not used for matching, so their match codes are empty. Finally, note that the XML returns the telephone number(s) and DOB where we have them.


<?xml version="1.0"?>
<validate_person_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>FULL</match_code_surname>
	<match_code_address>FULL</match_code_address>
	<match_code_postcode>FULL</match_code_postcode>
	<match_code_tel />
	<match_code_dob />
	<person>
		<line_1>19</line_1>
		<line_2>Snail Road</line_2>
		<line_3 />
		<place>Heslingdown</place>
		<town>York</town>
		<postcode>YO98 9ZR</postcode>
		<addr_single_line>19 Snail Road, Heslingdown, York, YO98 9ZR</addr_single_line>
		<title>Ms</title>
		<forename>Angela</forename>
		<middle_initial />
		<surname>Fanshawe</surname>
		<name_single_line>Ms Angela Fanshawe</name_single_line>
		<telephone_number />
		<mobile>(07921) 000000</mobile>
		<dob>1991-02-22</dob>
	</person>
</validate_person_res>

Fuzzy Match Example

Using these parameters to find our dummy record:-

Parameter Value
surname fanshaw
forename ANGELA
postcode YO989ZR
addr1 19 Snail
place
town York

...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"?>
<validate_person_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>
	<match_code_postcode>FULL</match_code_postcode>
	<match_code_tel />
	<match_code_dob />
	<person>
		<line_1>19</line_1>
		<line_2>Snail Road</line_2>
		<line_3 />
		<place>Heslingdown</place>
		<town>York</town>
		<postcode>YO98 9ZR</postcode>
		<addr_single_line>19 Snail Road, Heslingdown, York, YO98 9ZR</addr_single_line>
		<title>Ms</title>
		<forename>Angela</forename>
		<middle_initial />
		<surname>Fanshawe</surname>
		<name_single_line>Ms Angela Fanshawe</name_single_line>
		<telephone_number />
		<mobile>(07921) 000000</mobile>
		<dob>1991-02-22</dob>
	</person>
</validate_person_res>

Initial Match Example

Using these parameters to find our dummy record:-

Parameter Value
surname fanshawe
forename ANN
postcode YO989zr
addr1 19 Snail road
place
town York

...returned the XML below. Note that the match code for the forename is INITIAL.


<?xml version="1.0"?>
<validate_person_res>
	<mode>normal</mode>
	<t2a_version_number>2.2.3.8</t2a_version_number>
	<validation_status>FOUND</validation_status>
	<match_code_forename>INITIAL</match_code_forename>
	<match_code_surname>FULL</match_code_surname>
	<match_code_address>PARTIAL</match_code_address>
	<match_code_postcode>FULL</match_code_postcode>
	<match_code_tel />
	<match_code_dob />
	<person>
		<line_1>19</line_1>
		<line_2>Snail Road</line_2>
		<line_3 />
		<place>Heslingdown</place>
		<town>York</town>
		<postcode>YO98 9ZR</postcode>
		<addr_single_line>19 Snail Road, Heslingdown, York, YO98 9ZR</addr_single_line>
		<title>Ms</title>
		<forename>Angela</forename>
		<middle_initial />
		<surname>Fanshawe</surname>
		<name_single_line>Ms Angela Fanshawe</name_single_line>
		<telephone_number />
		<mobile>(07921) 000000</mobile>
		<dob>1991-02-22</dob>
	</person>
</validate_person_res>

Part Postcode and Full DOB

If we have a partial or incorrect postcode, the person may still be validated, if we have a full or partial DOB. Using these parameters to find our dummy record:-

Parameter Value
surname fanshawe
forename Angela
postcode YO98 7XX (the correct value is YO98 9ZR)
addr1 19 Snail road
place
town York
dob_y 1991
dob_m 2
dob_d 22

...returned the XML below. Because the full name and DOB were correct, and the address and postcode were partly matched, the method returns a record.


<?xml version="1.0"?>
<validate_person_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>FULL</match_code_surname>
	<match_code_address>PARTIAL</match_code_address>
	<match_code_postcode>FARTIAL</match_code_postcode>
	<match_code_tel />
	<match_code_dob>FULL</match_code_dob>
	<person>
		<line_1>19</line_1>
		<line_2>Snail Road</line_2>
		<line_3 />
		<place>Heslingdown</place>
		<town>York</town>
		<postcode>YO98 9ZR</postcode>
		<addr_single_line>19 Snail Road, Heslingdown, York, YO98 9ZR</addr_single_line>
		<title>Ms</title>
		<forename>Angela</forename>
		<middle_initial />
		<surname>Fanshawe</surname>
		<name_single_line>Ms Angela Fanshawe</name_single_line>
		<telephone_number />
		<mobile>(07921) 000000</mobile>
		<dob>1991-02-22</dob>
	</person>
</validate_person_res>

Using Name, DOB and Telephone

If your address and postcode values are incorrect or unavailable, the method can use the full name, full DOB and a telephone number. Using these parameters to find our dummy record:-

Parameter Value
surname fanshawe
forename Angela
dob_y 1991
dob_m 2
dob_d 22
telephone_number (07921) 000000 or 07921000000 or 00447921000000

...returned the XML below. Because the full name, DOB and telephone number were correct, the method returns a record.


<?xml version="1.0"?>
<validate_person_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>FULL</match_code_surname>
	<match_code_address />
	<match_code_postcode />
	<match_code_tel>FULL</match_code_tel>
	<match_code_dob>FULL</match_code_dob>
	<person>
		<line_1>19</line_1>
		<line_2>Snail Road</line_2>
		<line_3 />
		<place>Heslingdown</place>
		<town>York</town>
		<postcode>YO98 9ZR</postcode>
		<addr_single_line>19 Snail Road, Heslingdown, York, YO98 9ZR</addr_single_line>
		<title>Ms</title>
		<forename>Angela</forename>
		<middle_initial />
		<surname>Fanshawe</surname>
		<name_single_line>Ms Angela Fanshawe</name_single_line>
		<telephone_number />
		<mobile>(07921) 000000</mobile>
		<dob>1991-02-22</dob>
	</person>
</validate_person_res>