0151 355 4555



Searches the BT OSIS database and returns an array of DirectoryLookupResults that match the query. Due to licence restrictions, we can only return the first 200 matching results. Should you get an answer which has exactly 200 results then you would be best advised to narrow your criteria by selecting a more precise location or name.

The search criteria are handled with the following rules:

Name Restrictions

  • The surname can contain a wildcard (asterix *). If you do not specify one then it will not automatically add one.
  • A wildcard on the surname can only be added after 4 characters. (e.g smit*)
  • The Forename and MiddleName do not need to be specified, but if they are specified then they will further filter the results.
  • The Forename and MiddleName will automatically have a wildcard appended if they are just 1 character in length. (e.g. R will search for R*).
  • The Forename and MiddleName can have a manual wildcard added at any point (e.g. Rich*)

Location Restrictions

  • The location restrictions are specified by passing in the name of a locality and/or a (partial) postcode.
  • As a minimum, you must specify either a locality or partial postcode.
  • Any specified locality must be listed in full and be contained within this location list.
  • Postcodes can be specified as full postcodes or partial postcodes. Partial postcodes automatically have a wildcard appended on them.
  • Partial postcodes understand the hierarchical structure of a postcode. For example, specifying "B" (for Birmingham) does not include "BS" (for Bristol) despite the fact that they share the same first letter. Specifying "CH6" does not include "CH65".
  • You can specify both a postcode AND a locality - the results are AND'd together. For example "CH" and "LONDON" will return no records. "CH" and "CHESTER" will return records within CHESTER with a CH* postcode. It is generally not useful to specify both a postcode and a locality.

View all Telephone Directory (part of the identity validation suite) methods

Code Samples

<!-- Import the Integr8 Ajax API -->
<!-- NOTE: Get your own API key to use in the following script tag from: -->
<!-- http://www.data-8.co.uk/integr8/Admin/Ajax.aspx -->
<script src="https://webservices.data-8.co.uk/Javascript/Loader.ashx?key=your-api-key" type="text/javascript">

<script type="text/javascript">

function loadIntegr8() {
  // Load the TelephoneDirectory Integr8 service

function DirectoryLookup(name, postcode, town) {
  /// <param name="name">data8.name. Set up the Title, Forename, MiddleName, Surname properties before calling this method.</param>
  /// <param name="postcode">string</param>
  /// <param name="town">string</param>
  var telephonedirectory = new data8.telephonedirectory();

function showDirectoryLookupResult(result) {
  // Check that the call succeeded, and show the error message if there was a problem.
  if (!result.Status.Success) {
    alert('Error: ' + result.Status.ErrorMessage);
  else {
    // TODO: Process method results here.
    // Results can be extracted from the following fields:
    // result.Results
    //   Contains an array of results from the telephone directory for the requested search.
    //   Each item in the array contains TelephoneNumber, Name and Address fields which
    //   allow the extraction of the required details of each match.