Telephone Residential

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

This method gives you an online UK directory enquiries service within your website or office system, so that customers or staff can check and find phone numbers.

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.

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.
max_records	The maximum number of records to be returned. The default value is 200. 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 you 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.
fuzzy	Defaults to true. Set to true to enable fuzzy matching.

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.
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
invalid_name	The surname is too short. Enter at least 3 characters.
missing_surname	The surname is required
missing_place	The place is required.

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

Example XML Response

<telephone_res>
  <mode>test</mode>
  <status>ok</status>
  <credit_used>0</credit_used>
  <t2a_version_number>3.3.8.0</t2a_version_number>
  <person_list>
    <person>
      <line_1>56</line_1>
      <line_2>Sails Drive</line_2>
      <line_3/>
      <place/>
      <town>York</town>
      <postcode>YO10 3LR</postcode>
      <addr_single_line>56 Sails Drive, York, YO10 3LR</addr_single_line>
      <title>Ms</title>
      <forename>Janet</forename>
      <surname>Jackson</surname>
      <name_single_line>Ms Janet Jackson</name_single_line>
      <telephone_number>(01904) 560001</telephone_number>
    </person>
  </person_list>
</telephone_res>

Method Limits

The default max_records value is 200
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

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="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'  : 'sandbox',
                    '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=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;
        }

Telephone Residential

How it works

Mandatory Parameters

Optional Parameters

Returned Values

Error Codes

Free Test Mode

Example XML Response

Method Limits

Result Caching

Charging Policy

API key

Javascript key

API Endpoint & Authentication

Demo

Price calculator

Telephone Residential

How it works

Mandatory Parameters

Optional Parameters

Returned Values

Error Codes

Free Test Mode

Example XML Response

Method Limits

Result Caching

Charging Policy

API key

Javascript key

API Endpoint & Authentication

Demo

Price calculator

The demo javascript key has expired