Method List

Electoral Roll Search

Search the electoral roll for people by entering their name an/or their address/partial address.

This method will perform an Edited Electoral Roll search. It will return the name and address of UK residents over the age of 18 matching your search who have appeared on the Edited Electoral Register.

You can specify a full or partial address with the name to narrow down your search results. If you have the name of a second person residing at the same address, you can include this to narrow the result even further.

API method to use: electoral_roll

This method only searches the Electoral Roll. If you would like to search all our people data sources including Companies House and the Phone Book, please use the Find a Person method.

Restricted access

Please note the use of the full_electoral_roll method is only permitted to certain organisations e.g. local authorities and police forces. If you are such an organisation and interested in using the Full Electoral Roll, please apply for a corporate account

Note: The demo is using the electoral_roll method which only accesses records found in the edited register.

The full_electoral_roll method will respond with an error code if you have not been given access.

How it works

The method will return name and address results of UK residents over the age of 18 from the Electoral Roll, when the following data is supplied:

  • Name

OR

  • Full/partial address
  • Name of second resident (optional)

Please see the Documentation section for more information including a list of parameters and returned values.

Electoral roll search demo

A demo of the electoral_roll method can be found in the Demo section. Alternatively, you can see the T2A electoral roll search in action on ukphonebook.com.

API method to use: electoral_roll
|
Credits per use: 10

Search for a UK resident using the full/edited electoral register.
To seach the full electoral roll you need to use the full_electoral_roll API method.

Search the electoral register for a person or persons by entering their name and/or their address/partial address. You can also specify a 2nd resident to narrow your results further.

We provide name and address information for all UK residents over the age of 18 who have appeared on the electoral register.

Restricted access

Please note the use of the full_electoral_roll method is only permitted to certain organisations e.g. local authorities and police forces. This method will respond with an error code if you have not been given access.

The demo below is using the electoral_roll method which only accesses records found in the edited register.

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.
surname

The person's surname

Do not specify this if you wish to do an address-only search.
forename

The person's forename

Do not specify this if you wish to do an address-only search.
middle_initial

The person's second initial

Do not specify this if you wish to do an address-only search.
surname2

The 2nd resident's surname

It is possible to add a second name to your search so that it only finds records where both input criteria exist. e.g. only return records where a household contains a resident contained "smith" and "jones"
forename2

The 2nd resident's forename
middle_initial2

The 2nd residents second initial
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.
fuzzy Defaults to false. Set to true to enable 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 <electoral_roll_res> / <full_electoral_roll_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 :-

  • If a place_list is returned, the place name is ambiguous, and the final user should be given a selection from the list.
  • If a person_list is returned, the search has returned a list of people.
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.
premises_list

This is seen if the premises parameter is ambiguous or not specified; it is a free list of addresses at which there is data about the resident(s), and can be used to allow the end user to select the household to be viewed.

Use the name value from the selected premises to replace the premises input parameter value when re-invoking this method.

No charge is made when a premises_list is returned.
total_records

The total number of records, irrespective of the number displayed on any page.

This is only used when a person_list is present.
page_number

Current page being displayed, a zero-based integer.

This is only used when a person_list is present.
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.

This only occurs when max_records is set to higher than 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 electoral_roll and address_person methods.

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_list":["2009","2010","2011"],

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_surname

A surname OR some address details MUST be supplied.

When neither are supplied, it aborts with this error.

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, a place_list is returned.
  • If the surname is set (to anything) a dummy person_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>
      <director>N</director>
      <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>
      <director>N</director>
      <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 residents) , 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 the electoral_roll method

  • Invalid place
  • Invalid input (such as no surname)
  • No results found
  • 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="electoral-roll-example">
  <form class="electoral-roll-form">

    <div class="form-group">
          <label for="surname">Person's 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">Person's 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">Place</label>
          <input type="text" class="form-control" id="place" placeholder="Place, postcode or postcode area">
      </div>

    <div class="form-group">
          <label for="surname">Street</label>
          <input type="text" class="form-control" id="street" placeholder="Street name">
      </div>

    <div class="form-group">
          <label for="surname">Premises</label>
          <input type="text" class="form-control" id="premises" placeholder="Building name or number">
      </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>
                
.electoral-roll-example, .results {
  margin: 20px auto;
  width: 400px;
}

form.electoral-roll-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;
}
                
$(document).ready(function(){ 	
    $(".electoral-roll-form").submit(function(e) {
        e.preventDefault();	

        $('.error', $(this)).remove();

        var forename = $("#forename");        var surname = $("#surname");        var place = $("#place");        var street = $("#street");        var premises = $("#premises");        if($('.error', $(this)).length) {	
            $('.error', $(this)).first().next('input').focus();
        } else {
    
            $.ajax({
                url: 'https://api.t2a.io/rest/rest.aspx',
                dataType: 'json',
                data: {
                    'method'   : "electoral_roll",
                    'api_key'  : 'sandbox',
                    'forename' : forename.val(),
                    'surname' : surname.val(),
                    'place' : place.val(),
                    'street' : street.val(),
                    'premises' : premises.val(),
                    'output'   : 'json'
                    },
                success: function(result){
                    if(result.status == "error") {
                        $('#results-output').append('<p class="output"><strong>Error:</strong>' + result.error_code +'</p>');
                    } else {
                        var i = 0;
                        if(typeof result.person_list !== "undefined") {
                            result.person_list.forEach(function(person_list_item){
                                if(i>0){
                                    $('#results-output').append('<hr>');
                                }
                                var exceptionsArray = ['META', 'created_details', 'years_list', 'address_key', 'organisation_key', 'dob_details'];
                                    
                                for (var key in person_list_item) {
                                    if(!key.includes('id') && !exceptionsArray.includes(key) ) {
                                        var keyName = key.replace('_', ' ');
                                        $('#results-output').append('<p class="output"><span>' + keyName + ':</span> ' + person_list_item[key] + '</p>');
                                    }
                                }
                                i++;
                            });
                        }
                        var i = 0;
                        if(typeof result.place_list !== "undefined") {
                            result.place_list.forEach(function(place_list_item){
                                if(i>0){
                                    $('#results-output').append('<hr>');
                                }
                                var exceptionsArray = ['META', 'created_details', 'years_list', 'address_key', 'organisation_key', 'dob_details'];
                                    
                                for (var key in place_list_item) {
                                    if(!key.includes('id') && !exceptionsArray.includes(key) ) {
                                        var keyName = key.replace('_', ' ');
                                        $('#results-output').append('<p class="output"><span>' + keyName + ':</span> ' + place_list_item[key] + '</p>');
                                    }
                                }
                                i++;
                            });
                        }
                    }
                    $('.electoral-roll-example').hide();
                    $('.results').show(); 
               }
            });
        }
    });
    
    $('.results-return').on('click', function(e){
        e.preventDefault();
        $('#results-output').empty();
        
        $('.electoral-roll-example').show();
        $('.results').hide();
    });
});

function errorBefore(msg, insertBefore) {
    $('<p class="error">' + msg + '</p>').insertBefore(insertBefore);
}

Javascript key

<div class="electoral-roll-example">
  <form class="electoral-roll-form">

    <div class="form-group">
          <label for="surname">Person's 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">Person's 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">Place</label>
          <input type="text" class="form-control" id="place" placeholder="Place, postcode or postcode area">
      </div>

    <div class="form-group">
          <label for="surname">Street</label>
          <input type="text" class="form-control" id="street" placeholder="Street name">
      </div>

    <div class="form-group">
          <label for="surname">Premises</label>
          <input type="text" class="form-control" id="premises" placeholder="Building name or number">
      </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>
                
.electoral-roll-example, .results {
  margin: 20px auto;
  width: 400px;
}

form.electoral-roll-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;
}
                
$(document).ready(function(){ 	
    $(".electoral-roll-form").submit(function(e) {
        e.preventDefault();	

        $('.error', $(this)).remove();

        var forename = $("#forename");        var surname = $("#surname");        var place = $("#place");        var street = $("#street");        var premises = $("#premises");        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'   : "electoral_roll",
                                'javascript_key'  : result.javascript_key,
                                'domain' : "t2a.io", 
                                'forename' : forename.val(),
                                'surname' : surname.val(),
                                'place' : place.val(),
                                'street' : street.val(),
                                'premises' : premises.val(),
                                'output'   : 'json'
                            },
                            success: function(result){
                        if(result.status == "error") {
                            $('#results-output').append('<p class="output"><strong>Error:</strong>' + result.error_code +'</p>');
                        } else {
                            var i = 0;
                            if(typeof result.person_list !== "undefined") {
                                result.person_list.forEach(function(person_list_item){
                                    if(i>0){
                                        $('#results-output').append('<hr>');
                                    }
                                    
                                    var exceptionsArray = ['META', 'created_details', 'years_list', 'address_key', 'organisation_key', 'dob_details'];
                                    
                                    for (var key in person_list_item) {
                                        if(!key.includes('id') && !exceptionsArray.includes(key) ) {
                                            var keyName = key.replace('_', ' ');
                                            $('#results-output').append('<p class="output"><span>' + keyName + ':</span> ' + person_list_item[key] + '</p>');
                                        }
                                    }
                                    i++;
                                });
                            }
                            var i = 0;
                            if(typeof result.place_list !== "undefined") {
                                result.place_list.forEach(function(place_list_item){
                                    if(i>0){
                                        $('#results-output').append('<hr>');
                                    }
                                    
                                    var exceptionsArray = ['META', 'created_details', 'years_list', 'address_key', 'organisation_key', 'dob_details'];
                                    
                                    for (var key in place_list_item) {
                                        if(!key.includes('id') && !exceptionsArray.includes(key) ) {
                                            var keyName = key.replace('_', ' ');
                                            $('#results-output').append('<p class="output"><span>' + keyName + ':</span> ' + place_list_item[key] + '</p>');
                                        }
                                    }
                                    i++;
                                });
                            }
                       }
                                $('.electoral-roll-example').hide();
                                $('.results').show(); 
                            }
                        });
                    }
                }
            });
        }
    });
    
    $('.results-return').on('click', function(e){
        e.preventDefault();
        $('#results-output').empty();
        
        $('.electoral-roll-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;
        }

API Endpoint & Authentication

Demo

Search the UK edited electoral register. Either a surname or a place is required.

Price calculator

Price Calculator

Number of checks: 50 Price per check: 50p