Find A Person
Search the edited electoral roll, the phone book, Companies House data and consumer data for a person
The majority of websites, apps and CRM systems use name and address data. It’s vital that this data is as accurate as possible for many reasons such as speeding up the user journey and validating purchases.
Our API method to find a person searches a vast UK dataset including the edited electoral roll, phone book data, Companies House and consumer data.
How it works
The method returns a list of names and addresses for UK residents that match your search criteria, when the following data is supplied:
- a name and/or address
- a partial name and/or address
Supplying an address only will return all occupants at that address. Additional optional parameters can also be supplied to the method such as age and gender.
Please see the Documentation section for more detailed information on all mandatory and optional parameters, as well as a list of all returned values.
Person search demo
A demo of the person_search method can be found in the Demo section. Alternatively, you can see the T2A person search in action on ukphonebook.com.
Searches the edited electoral register, phone book, companies house and consumer data for a UK resident.
Enter a name and/or address, or a partial name and/or address to find all UK residents matching your search criteria.
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. |
Optional Parameters
Name | Description |
---|---|
client | You can optionally include an identifier for your final client or user. This is logged in your usage log and you will be able to view your usage statistics by client. |
output | Set to json for a JSON response; the default response is XML. Not applicable to the SOAP API. |
callback | When using JSON, specify a JSONP wrapper in which the JSON response is to be wrapped. |
records_per_page | Specify the number of records to return on the current page. We offer page caching for this method - once your search is invoked, we store the pages on our server for 60 minutes; a subsequent request for a page of results from that search is displayed from the cache, at no charge to you. See result page caching. |
page_num | Zero based integer - current page number to return. |
name |
The person's name, for example:- Mr John D Fawcett Do not specify this if you wish to do an address-only search. T2A will parse the name into the relevant components. |
name2 |
The name of a 2nd resident The person_search method allows you to search for records where T2A will parse the name into the relevant components. |
forename |
The person's forename, for example:- To make the person_search more flexible we allow you to input the components of a name (forename, middleinitial and lastname) separately. Do not use these distinct parameters if you have specfied a |
middleinitial |
The person's middle initial, this will filter out any records which do not have this middle initial. Please note some data sources may not record the person's middle initial. To make the person_search more flexible we allow you to input the components of a name (forename, middleinitial and lastname) separately. Do not use these distinct parameters if you have specfied a |
lastname |
The person's lastname, for example:- To make the person_search more flexible we allow you to input the components of a name (forename, middleinitial and lastname) separately. Do not use these distinct parameters if you have specfied a |
forename2 |
The forename of a second resident, the person_search method allows you to search for records where two names are found at the same address. |
middleinitial2 |
The middleinitial of a second resident, the person_search method allows you to search for records where two names are found at the same address. |
lastname2 |
The lastname of a second resident, the person_search method allows you to search for records where two names are found at the same address. |
place | Enter a UK place, postcode, or postcode area. Do not specify this to do a national UK search. |
street | The street name. |
premises | The house number or name. |
sex |
Set to m or f to specify the gender to be returned, where that gender is known. This parameter is only applicable to electoral roll data; any results from other data sources are not filtered by this parameter. |
dob_y |
Enter a year element for a date of birth in the format yyyy to filter records by age |
dob_m |
Enter a month element for a date of birth in the format mm to filter records by age. Range of values is: 01 - 12 |
dob_d |
Enter a day element for a date of birth in the format dd to filter records by age. Range of values: 01 - 31 |
min_age |
Enter a minimum age to filter records by |
max_age |
Enter a maximum age to filter records by |
use_er | Set to false to NOT search the electoral register. Defaults to true. |
use_osis | Set to false to NOT search the phone book. Defaults to true. |
use_director | Set to false to NOT search for directors using Companies House. Defaults to true. |
fuzzy | Defaults to true. Set to false to disable fuzzy matching. |
max_records |
The maximum number of records to be returned. The default value is 1,000. The absolute maximum number of records allowed is 10,000. If the number of records returned exceeds the maximum value, a “too_many” error will be returned but if you set a max_records value higher than 10,000 the result list will be capped at 10,000. |
records_per_page |
The number of records returned on the current page. Defaults to 200. Set to a factor of 200, such as 10,20 or 25 to return the <person> records in smaller chunks. Each block of 200 records is chargeable, so, for example, if your search returns 250 records, and your records_per_page is 25, pages 0-7 (parameter page_num, is zero-based) are already paid for, but if the 9th page of results is viewed, a credit value is debited. |
Returned Values
The XML response is contained within a <person_search_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. |
mode | Returns normal or test when executed in the
free test mode. |
person_list |
An array of person records. Only one of the lists is present :-
|
place_list | An array of place records. This is present if the place
name is ambiguous. No charge is made when a place_list is retuned. |
total_records |
The total number of records, irrespective of the number displayed on any page. This is only used when a |
page_number |
Current page being displayed, a zero-based integer. This is only used when a |
er_searched | Set to true if the electoral roll data was searched. |
telephone_data_searched |
Set to true if the telephone data was searched. Note that licensing restrictions prevent telephone data being searched if:-
|
uncapped_total |
The total number of person records, when the result as
capped at a maximum of 10,000; total_records will be
10,000.
|
The values in the <person>
element.
Name |
Type |
Description |
---|---|---|
title |
string |
The person’s title, such as Mr, Mrs, Ms etc. |
forename |
string |
The person’s first name |
middle_initial |
string |
The second initial |
surname |
string |
The person’s surname |
name_single_line |
string |
The name on a single line, comprising title, forename, middle initial and surname; for example:- Mr Alan Fiction Jean A Dreamer |
line_1 |
string |
Address line 1 |
line_2 |
string |
Address line 2 |
line_3 |
string |
Address line 3 |
place |
string |
The place. If the address is in a named area within a large town, this will be that area, otherwise it will be the town. place is never empty if town is set. |
town |
string |
The town; only used if the address is in a named area within that town. |
postcode |
string |
The UK postal code, formatted to include the space. |
addr_single_line |
string |
The address, formatted as a single line. Commas are inserted between the major elements, and the postcode is included, if available. |
years_list |
string |
A list of years, in which the electoral roll record for this person has been found.
This is only set by the Please note that the XML returns an array of Strings; each year is a single String:- <years_list> <string>2008</string> <string>2009</string> <string>2010</string> <string>2011</string> </years_list> The JSON returns an array of years thus:-
|
years_text |
string |
A simple string describing the years range, such as 2017- |
telephone_number |
string |
The person’s telephone number. |
mobile |
string |
The person’s mobile phone number |
Error Codes
Name |
Description |
---|---|
missing_place |
The place parameter is mandatory if only the UK telephone data is being searched. |
invalid_dob |
The dob_? parameters used are invalid. |
See the common error codes.
Free Test Mode
When operating in the free test mode errors are returned if mandatory parameters are missing, or it returns a dummy data response, in an identical format to a real response.
Note that the mode
is returned as test
when the method is operating in the free test mode.
The free test mode for this method operates in the following manner:-
- If the
place
parameter is set to leeds, aplace_list
is returned. - If the
surname
is set (to anything) a dummyperson_list
is returned.
Example XML Response
<electoral_roll_res> <mode>test</mode> <status>ok</status> <credit_used>0</credit_used> <t2a_version_number>3.3.7.9a</t2a_version_number> <person_list> <person> <line_1>17</line_1> <line_2>Imagination Gardens</line_2> <line_3>Virtual Road</line_3> <place>Heslington</place> <town>York</town> <postcode>YO91 3X0</postcode> <addr_single_line> 17 Imagination Gardens, Virtual Road, Heslington, York, YO91 3X0 </addr_single_line> <years_text>2019-</years_text> <years_list> <string>2019</string> <string>2020</string> </years_list> <title>Mr</title> <forename>Alan</forename> <surname>Fiction</surname> <name_single_line>Mr Alan Fiction</name_single_line> <created_details> <y>2019</y> <m>2</m> <d>1</d> <en>1 Feb 2019</en> </created_details> </person> <person> <line_1>17</line_1> <line_2>Imagination Gardens</line_2> <line_3>Virtual Road</line_3> <place>Heslington</place> <town>York</town> <postcode>YO91 3X0</postcode> <addr_single_line> 17 Imagination Gardens, Virtual Road, Heslington, York, YO91 3X0 </addr_single_line> <years_text>2019-</years_text> <years_list> <string>2019</string> <string>2020</string> </years_list> <title>Mrs</title> <forename>Janet</forename> <surname>Fiction</surname> <name_single_line>Mrs Janet Fiction</name_single_line> <created_details> <y>2019</y> <m>2</m> <d>1</d> <en>1 Feb 2019</en> </created_details> </person> </person_list> </electoral_roll_res>
Method Limits
- The default max_records value is 1,000
- The max_records parameter may be set to up to 10,000; if max_records is set to over 10,000, the method caps the total records to 10,000 and reports the actual total as uncapped_total; this is to avoid breaking existing code, by presenting unexepected “too_many” errors.
Result Caching
When a chargeable result is found (a list of persons) , the list is cached on our server for 60 minutes. If the successful search is repeated during that time, the list is displayed, but there is no charge.
Charging Policy
The method only charges when a valid name and/or address has been supplied.
A credit charge is then levied for every new consecutive block of 200 records viewed.
The following events are not chargeable for this method
- Invalid place
- Invalid input
- Too many results found
There are two ways to authenticate your application with the T2A API. The two implementation examples on this page cover each type of authentication
We recommend using an API key for internal applications and the javascript key for public facing applications where you would want to protect your API key.
Please note: The examples below run on a sandbox environment which return sample data. To quality check the data we provide, up to 3 free searches are available in the demo tab with results showing live [REDACTED] data.
API key
<div class="person-search-example"> <form class="person-search-form"> <div class="form-group"> <label for="surname">Surname</label> <input type="text" class="form-control" id="surname" placeholder="Person's surname e.g Fawcett"> </div> <div class="form-group"> <label for="surname">Forename</label> <input type="text" class="form-control" id="forename" placeholder="Person's forename e.g John"> </div> <div class="form-group"> <label for="surname">Postcode</label> <input type="text" class="form-control" id="postcode" placeholder="UK Postcode"> </div> <div class="form-group"> <label for="surname">Address</label> <input type="text" class="form-control" id="addr1" placeholder="UK Address (First line)"> </div> <button type="submit" class="btn example-submit">Submit</button> </form> </div> <div class="results"> <div id="results-output"></div> <a class="results-return" href="#">Back to search</a> </div>
.person-search-example, .results { margin: 20px auto; width: 400px; } form.person-search-form, .results { background-color: #F6F6F6; border: 1px solid #CBCBCB; padding: 15px; } .example-submit { background-color: #F0614C; border-radius: 2px; font-size: 11px; font-weight: 400; color: #fff; text-transform: uppercase; letter-spacing: 0.193em; width: 138px; height: 41px; margin-top: 10px; } .results { display: none; } .results-return { font-weight: 600; color: #F0614C; } #results-output span { font-weight: bold; text-transform: capitalize; } #results-output hr { border-top: 1px solid #000; } .error { font-size: 11px; color: #f00; } p.not_found { font-weight: bold; color: red; } p.found_under_18 { font-weight: bold; color: red; } p.found { font-weight: bold; color: green; }
$(document).ready(function(){ $(".person-search-form").submit(function(e) { e.preventDefault(); $('.error', $(this)).remove(); var surname = $("#surname"); if(!surname.val()) { errorBefore("Please enter a surname.", surname); } var forename = $("#forename"); if(!forename.val()) { errorBefore("Please enter a forename.", forename); } var postcode = $("#postcode"); if(!postcode.val()) { errorBefore("Please enter a postcode.", postcode); } var addr1 = $("#addr1"); if(!addr1.val()) { errorBefore("Please enter an address.", addr1); } if($('.error', $(this)).length) { $('.error', $(this)).first().next('input').focus(); } else { $.ajax({ url: 'https://api.t2a.io/rest/rest.aspx', dataType: 'json', data: { 'method' : "person_search", 'api_key' : 'sandbox', 'surname' : surname.val(), 'forename' : forename.val(), 'postcode' : postcode.val(), 'addr1' : addr1.val(), 'output' : 'json' }, success: function(result){ if(result.validation_status == "NOT_FOUND") { $('#results-output').append('<p class="output not_found">'+forename.val()+' '+surname.val()+' was not found at the specificed address') }; if(result.validation_status == "FOUND_UNDER_18") { $('#results-output').append('<p class="output found_under_18">'+forename.val()+' '+surname.val()+' was found at the specified address, but we cannot confirm they are over 18') }; if(result.validation_status == "FOUND") { $('#results-output').append('<p class="output found">'+forename.val()+' '+surname.val()+' was found at the specified address and is over 18') }; $('.person-search-example').hide(); $('.results').show(); } }); } }); $('.results-return').on('click', function(e){ e.preventDefault(); $('#results-output').empty(); $('.person-search-example').show(); $('.results').hide(); }); }); function errorBefore(msg, insertBefore) { $('<p class="error">' + msg + '</p>').insertBefore(insertBefore); }
Javascript key
<div class="person-search-example"> <form class="person-search-form"> <div class="form-group"> <label for="surname">Surname</label> <input type="text" class="form-control" id="surname" placeholder="Person's surname e.g Fawcett"> </div> <div class="form-group"> <label for="surname">Forename</label> <input type="text" class="form-control" id="forename" placeholder="Person's forename e.g John"> </div> <div class="form-group"> <label for="surname">Postcode</label> <input type="text" class="form-control" id="postcode" placeholder="UK Postcode"> </div> <div class="form-group"> <label for="surname">Address</label> <input type="text" class="form-control" id="addr1" placeholder="UK Address (First line)"> </div> <button type="submit" class="btn example-submit">Submit</button> </form> </div> <div class="results"> <div id="results-output"></div> <a class="results-return" href="#">Back to search</a> </div>
.person-search-example, .results { margin: 20px auto; width: 400px; } form.person-search-form, .results { background-color: #F6F6F6; border: 1px solid #CBCBCB; padding: 15px; } .example-submit { background-color: #F0614C; border-radius: 2px; font-size: 11px; font-weight: 400; color: #fff; text-transform: uppercase; letter-spacing: 0.193em; width: 138px; height: 41px; margin-top: 10px; } .results { display: none; } .results-return { font-weight: 600; color: #F0614C; } #results-output span { font-weight: bold; text-transform: capitalize; } #results-output hr { border-top: 1px solid #000; } .error { font-size: 11px; color: #f00; } p.not_found { font-weight: bold; color: red; } p.found_under_18 { font-weight: bold; color: red; } p.found { font-weight: bold; color: green; }
$(document).ready(function(){ $(".person-search-form").submit(function(e) { e.preventDefault(); $('.error', $(this)).remove(); var surname = $("#surname"); if(!surname.val()) { errorBefore("Please enter a surname.", surname); } var forename = $("#forename"); if(!forename.val()) { errorBefore("Please enter a forename.", forename); } var postcode = $("#postcode"); if(!postcode.val()) { errorBefore("Please enter a postcode.", postcode); } var addr1 = $("#addr1"); if(!addr1.val()) { errorBefore("Please enter an address.", addr1); } if($('.error', $(this)).length) { $('.error', $(this)).first().next('input').focus(); } else { $.ajax({ url: 'https://t2a.io/ajax/getExampleJSKey', dataType: 'json', success: function (result) { if (result.status) { $.ajax({ url: 'https://api.t2a.io/rest/rest.aspx', dataType: 'json', data: { 'method' : "", 'javascript_key' : result.javascript_key, 'domain' : "t2a.io", 'surname' : surname.val(), 'forename' : forename.val(), 'postcode' : postcode.val(), 'addr1' : addr1.val(), 'output' : 'json' }, success: function(result){ if(result.validation_status == "NOT_FOUND") { $('#results-output').append('<p class="output not_found">'+forename.val()+' '+surname.val()+' was not found at the specificed address') }; if(result.validation_status == "FOUND_UNDER_18") { $('#results-output').append('<p class="output found_under_18">'+forename.val()+' '+surname.val()+' was found at the specified address, but we cannot confirm they are over 18') }; if(result.validation_status == "FOUND") { $('#results-output').append('<p class="output found">'+forename.val()+' '+surname.val()+' was found at the specified address and is over 18') }; $('.person-search-example').hide(); $('.results').show(); } }); } } }); } }); $('.results-return').on('click', function(e){ e.preventDefault(); $('#results-output').empty(); $('.person-search-example').show(); $('.results').hide(); }); }); function errorBefore(msg, insertBefore) { $('<p class="error">' + msg + '</p>').insertBefore(insertBefore); }
This example first needs to call to a file on your server, which will provide the user with an API key from your javascript key.
In our example above we have used a PHP file located at ajax/getExampleJSKey
which looks like the example below
<?php $url = 'https://api.t2a.io/rest/rest.aspx' . "?method=javascript_key" . "&api_key=sandbox" . . "&domain=" . $_SERVER['HTTP_HOST']; . '&ip_address=' . get_user_ip() . "&lifetime_minutes=10"; $result = simplexml_load_file($url); if ($result->javascript_key) { echo (string)$result->javascript_key; }