Find a UK Residential Telephone number

Search the phone book to find a UK residential phone number.


This method enables you to have an online UK directory enquiries service integrated into your website, CRM system or other application.

Searching the phone book to access current UK telephone data, which is updated daily, this is the most up-to-date and accurate telephone data available.

The uses of finding a residential telephone number are many and varied, including helping businesses achieve more outbound sales calls to customers and prospects, and facilitating better customer service where a telephone conversation is more desirable than an email.

API method to use: telephone_residential

How it works

The method will return a UK residential telephone number that is present in the Phone Book, when the following data is supplied:

  • Name
  • City, town or postcode

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

Next Steps…

We will give you a unique API key to allow you to test the method using credits on your T2A account. The Demo tab will allow you to test the parameters required and view the result.

If you do not have an account you will first need to sign up

 

Let's get started

 

 

Other related API methods:

Telephone number appending
Check if a number is TPS (Telephone Preference Service) registered
Bulk TPS checking
Find a business telephone number

API method to use: telephone_residential
|
Credits per use: 2.5

Search the phone book to find a UK residential phone number.

Derived from the current UK telephone data, which is updated daily, the T2A API provides access to the most up-to-date and accurate telephone data available.

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 A persons surname or partial surname, use the '*' for wild card searches e.g. "Johnson" or "John*"
place Enter a UK place, postcode, or postcode area.

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.
forename The person forename or initials.
street The street name.
premises The building number or name.
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.

Returned Values


The XML response is contained within a <telephone_residential_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.

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 person_list is present.

page_number

Current page being displayed, a zero-based integer.

This is only used when a person_list is present.

Error Codes


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

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 not, a dummy person_list is returned.

Example XML Response



<?xml version="1.0"?>
<people_search_res>
  <mode>test</mode>
  <t2a_version_number>1.0.0</t2a_version_number>
  <status>ok</status>
  <credit_used>0</credit_used>
  <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>
      <title>Mr</title>
      <forename>Alan</forename>
      <surname>Fiction</surname>
      <name_single_line>Mr Alan Fiction</name_single_line>
      <telephone_number>(01904) 000000</telephone_number>
      <years_list>
        <string>2009</string>
        <string>2010</string>
        <string>2011</string>
      </years_list>
	  <mobile></mobile>
	  <dob>1974-12-01</dob>
	  <email_address>alan.fiction@gmail.com</email_address>
    </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>
      <title>Mrs</title>
      <forename>Anne</forename>
      <middle_initial>J</middle_initial>
	  <surname>Fiction</surname>
      <name_single_line>Mrs Anne J Fiction</name_single_line>
      <telephone_number>(01904) 000000</telephone_number>
      <years_list>
        <string>2009</string>
        <string>2010</string>
        <string>2011</string>
      </years_list>
	  <mobile></mobile>
	  <dob>1980-06-08</dob>
	  <email_address>anne.j.fiction@gmail.com</email_address>	  
    </person>
  </person_list>
  <er_searched>true</er_searched>
  <telephone_data_searched>true</telephone_data_searched>
</people_search_res>

Enter a person's surname and their location to search for their phone number.

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.

Note: examples below show a restricted result set with a maximum of 3 results per search

API key


<div class="telephone-residential-example">
  <form class="telephone-residential-form">

    <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 (optional)</label>
          <input type="text" class="form-control" id="street" placeholder="Street name">
      </div>

    <div class="form-group">
          <label for="surname">Premises (optional)</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>
                
.telephone-residential-example, .results {
  margin: 20px auto;
  width: 400px;
}

form.telephone-residential-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(){ 	
    $(".telephone-residential-form").submit(function(e) {
        e.preventDefault();	

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

        var surname = $("#surname");        if(!surname.val()) {
                errorBefore("Please enter a person's surname.", surname);
            }

        var place = $("#place");        if(!place.val()) {
                errorBefore("Please enter a 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'   : "telephone_residential",
                    'api_key'  : 'P8o5ap-6bisM1YCs3EKB_4Kz0ShtTW9jShYhhLgEgy_1',
                    '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++;
                            });
                        }
                    }
                    $('.telephone-residential-example').hide();
                    $('.results').show(); 
               }
            });
        }
    });
    
    $('.results-return').on('click', function(e){
        e.preventDefault();
        $('#results-output').empty();
        
        $('.telephone-residential-example').show();
        $('.results').hide();
    });
});

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

Javascript key


<div class="telephone-residential-example">
  <form class="telephone-residential-form">

    <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 (optional)</label>
          <input type="text" class="form-control" id="street" placeholder="Street name">
      </div>

    <div class="form-group">
          <label for="surname">Premises (optional)</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>
                
.telephone-residential-example, .results {
  margin: 20px auto;
  width: 400px;
}

form.telephone-residential-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(){ 	
    $(".telephone-residential-form").submit(function(e) {
        e.preventDefault();	

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

        var surname = $("#surname");        if(!surname.val()) {
                errorBefore("Please enter a person's surname.", surname);
            }

        var place = $("#place");        if(!place.val()) {
                errorBefore("Please enter a 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'   : "telephone_residential",
                                'javascript_key'  : result.javascript_key,
                                'domain' : "t2a.io", 
                                '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++;
                                });
                            }
                       }
                                $('.telephone-residential-example').hide();
                                $('.results').show(); 
                            }
                        });
                    }
                }
            });
        }
    });
    
    $('.results-return').on('click', function(e){
        e.preventDefault();
        $('#results-output').empty();
        
        $('.telephone-residential-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=P8o5ap-6bisM1YCs3EKB_4Kz0ShtTW9jShYhhLgEgy_1" .
            . "&domain=" . $_SERVER['HTTP_HOST'];
            . '&ip_address=' . $_SERVER['REMOTE_ADDR']
            . "&lifetime_minutes=10";

        $result = simplexml_load_file($url);

        if ($result->javascript_key) {
            echo (string)$result->javascript_key;
        }