Identity Management Web Service: UK Telephone Directory Integration
This guide explains how to access GBGroup's web service products using their Identity Management Platform (IdM), available via SOAP web services. The document provides a general description of the available functionality along with a definition of the corresponding interfaces used to access different datasets and services.
The fundamentals of integrating with the service are described here: Integration Fundamentals
The next section of this document gives product specific details regarding the use of the IdM UK Telephone Directory Web Service products via IdM.
Matchcode UK Telephone Web Service Product Information
The UK Telephone Directory web service product provides access to UK telephone directory information (an extract from BT OSIS). There are two services available selected via different profiles Directory Enquiry and Teleappend.
The UK Telephone Directory Service products are available via the Identity Management ExecuteCapture web service method.
UK Telephone Directory - Input Information
The UK Telephone Directory services take name/organisation and address information and returns telephone numbers matching the name/organisation and address supplied. However there are certain rules regarding the minimum information that must be supplied depending on whether the Directory Enquiry or Teleappend profile is specified. Similarly the two services produce different levels of response details. These are all detailed in the relevant sections below.
ProfileRequestCapture Information
The ProfileRequestCapture structure contains the criteria to identify the target product being called.
In the profileRequest element, the profileGuid should be specified as:
| Profile | GUID |
|---|---|
| UK Telephone number - Directory Enquiries | C4915B34-639A-45AB-B6D5-75F61DFE73B9 |
| UK Telephone number - Tele-Append | 5C29EE0D-5710-4C21-9D79-D6341B18A855 |
UK Telephone Input Criteria
Both Directory Enquiry and Teleappend UK Telephone Directory criteria should be entered into the IdmDataSearchAddress data structure:
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → IdmDataSearchAddress
The person details are entered in the IdmDatacapturePerson structure as follows:
| Field Name | Type | Description |
|---|---|---|
| firstname | String | First Name |
| lastname | String | Last Name |
The firstname field, if used, must contain the first name exactly as listed in the public telephone directory. This is often the first initial, or first and middle initial. E.g. WA (Smith) for Bill Anthony (Smith). For a good match, it is often best if the first name is omitted from the search criteria altogether.
Directory Enquiry
To perform a directory enquiry search the following rules apply:-
- There must be a full surname or organisation name, or a minimum of three characters in the surname or organisation before any wildcard characters.
- There can be a combination of one or more locality fields entered (postcode, stateRegion, town, locality, subLocality, however the resultant combination must identify a unique locality.
e.g.
A full postcode is acceptable.
A town on it's own is acceptable if there if there is only one town in the country with that name (e.g. Middlesbrough)
Towns or localities which are not unique will have to be qualified with a stateRegion or further locality/sublocality information. (e.g. St. Helens, Merseyside or St. Helens, Isle of Wight).
If the name/organisation is not sufficient the response will indicate insufficient criteria
If the locality is not sufficiently unique the response will include a list of possible localities as a picklist and the request will need to be re-submitted with greater locality detail (see section on output details)
Teleappend
To perform a teleappend the following rules apply:
- There must be a full surname or organisation name, no wildcard characters are allowed.
- This must be a uniquely specified address. The minimum requirements are a full postcode plus unique building number/name
If the name/organisation plus address information is not sufficiently unique the response will indicate insufficient criteria.
Telephone Output Format
The results of a UK Telephone Directory search are returned in a ProfileResponseDetails structure with a ProfileResponseDetail.responseType of 'CAPTURE'.
The ProfileResponseDetails structure contains a single CaptureResponse data structure which holds an array of IdmDataAddress records containing the returned address data.
ExecuteCaptureResponse > ProfileResponse [0] > ProfileResponseDetails [0] > CaptureResponse > CaptureResponseData > IdmDataAddress [n]
Additional Items
The returned phone information is returned in the additionalItems field
For lookups on a name this will be in the person additionalItems structure
For lookups on an organisation this will be in the address additionalItems structure
| Key | Value |
|---|---|
| BtOsisNumber | Telephone Number |
Directory Enquiry
A maximum of 200 numbers can be returned from a directory enquiry search. The first 200 found will be returned. It is not possible to 'page' through to the next 200, to reduce the number below 200 requires more detailed input criteria.
If the locality for the input address for a Directory Enquiry is ambiguous a list of suggestions may be returned. The resultStatus will be returned as PICKLIST containing a list of more detailed locality information suggestions. The alternative locality information will populate the appropriate address fields of an IdmDataAddress structure.
Teleappend
If the phone number for a teleappend query is Ex Directory then the telephone number field will be returned with the text "Ex Directory"
A teleappend can only return a single result. If the name/organidation and address supplied yields more than one result then no numbers are returned unless one of the numbers is not Ex Directory and all the others are in which case the non Ex Directory number will be returned.
Sample XML
Sample Directory Enquiry Lookup XML
The following XML sample demonstrates a request data object containing a name and Address (note this is dummy data).
<!-- request input data - name and address -->
<mes:requestdata>
<req:address>
<data:organisation/>
<data:street/>
<data:town></data:town>
<data:postcode>cr1 1ab</data:postcode>
<data:locality></data:locality>
<data:subbuilding/>
<data:building></data:building>
<data:sublocality/>
<data:stateregion/>
<data:countrycode>gbr</data:countrycode>
<data:pobox/>
<data:freeformataddress></data:freeformataddress>
<data:additionalitems tmp="?"></data:additionalitems>
<data:persons tmp="?">
<data:person>
<data:lastname>pode</data:lastname>
</data:person>
</data:persons>
</req:address>
<req:filters tmp="?"></req:filters>
<req:options></req:options>
</mes:requestdata>Sample Directory Enquiry Lookup JSON
{
"customerreference": "test",
"profileguid": "c4915b34-639a-45ab-b6d5-75f61dfe73b9",
"configurationid": "1",
"requestdata": {
"address": {
"countrycode": "gbr",
"postcode": "cr1 1ab",
"persons": {"person":[{"lastname":"pode"}]}
},
"options": {
"addressenvelopeformat": "a4p",
"offset": "0",
"maxreturn": "100",
"casing": "mixed"
}
}
}Sample Directory Enquiry Lookup Output XML
The following output XML demonstrates the CaptureResponse for the above UK Telephone Directory lookup.
<!-- uk telephone directory component response -->
<mes:captureresponse>
<req:resultstatus>single</req:resultstatus>
<req:recordsreturned>1</req:recordsreturned>
<req:moredata>false</req:moredata>
<req:totalrecordcount>1</req:totalrecordcount>
<req:totalpages>1</req:totalpages>
<req:matchscore>0</req:matchscore>
<req:responsecount>0</req:responsecount>
<req:response>
<req:address>
<data:street>panic street</data:street>
<data:town>croydon</data:town>
<data:postcode>cr1 1ab</data:postcode>
<data:buildingnumber>42</data:buildingnumber>
<data:stateregion>surrey</data:stateregion>
<data:countrycode>gbr</data:countrycode>
<data:dpszipplus>1ab</data:dpszipplus>
<data:additionalitems/>
<data:persons>
<data:person>
<data:firstname>e</data:firstname>
<data:lastname>pode</data:lastname>
<data:additionalitems>
<data:item>
<data:key>btosisnumber</data:key>
<data:value>02086666666</data:value>
</data:item>
</data:additionalitems>
</data:person>
</data:persons>
</req:address>
</req:response>
</mes:captureresponse>Sample Directory Enquiry Lookup Output JSON
{
"profileheader": {
"profileguid": "c4915b34-639a-45ab-b6d5-75f61dfe73b9",
"profilename": "uk telephone number - directory enquiries",
"transactionguid": "35709294-c86f-4af9-aaf7-5a94cf88a1b9",
"transactiontimestamp": 1433340700402,
"profilestatus": "success",
"remarks": null
},
"profileresponsedetails": [ {
"transactionguid": "aed2af23-eed4-4d80-bf43-b5edce49777e",
"componentname": "osis - directory enquiry capture service",
"componentstatus": "success",
"componentaction": "directory_enquiry",
"responsetype": "capture",
"notes": "[]",
"invoice": {
"invoicelist": [ {
"invoiceguid": "521790f5-b687-4aa4-bec6-fb24ec63d59f",
"billinginformationguid": "3e1c4c82-ed38-4bcf-a7bb-f92d26814294",
"datalicencedescription": null,
"billingpoints": 1,
"creditsused": 1,
"datasetinvoices": [ {
"datasetcode": "directory_enquiry",
"billingpoints": 1,
"recordsreturned": 1,
"datalicenceguid": "3e1c4c82-ed38-4bcf-a7bb-f92d26814294"
}]
}],
"tmp": null
},
"captureresponse": {
"resultstatus": "single",
"resultstatusdetail": null,
"recordsreturned": 1,
"moredata": false,
"totalrecordcount": 1,
"totalpages": 1,
"matchscore": 0,
"matchlevel": null,
"outputstatus": null,
"fieldstatus": null,
"responsecount": 1,
"response": [ {
"input": null,
"address": [ {
"organisation": null,
"street": "panic street",
"town": "croydon",
"postcode": "cr1 1ab",
"locality": null,
"addpoint": null,
"department": null,
"subbuilding": null,
"buildingnumber": "11",
"buildingname": null,
"buildinggroup": null,
"pobox": null,
"substreet": null,
"sublocality": null,
"stateregion": "surrey",
"subadministrativearea": null,
"administrativearea": null,
"superadministrativearea": null,
"countrycode": "gbr",
"countryname": null,
"dpszipplus": "1ab",
"formattedaddress": null,
"geographicinformation": null,
"additionalitems": {
"item": [],
"tmp": null
},
"groupedadditionalitems": [],
"persons": {
"person": [ {
"title": null,
"gender": null,
"firstname": "e",
"middlename": null,
"lastname": "pode",
"dateofbirth": null,
"firstyearofresidency": null,
"lastyearofresidency": null,
"yearsofresidency": null,
"consentedlandlines": [],
"consentedmobiles": [],
"consentedemails": [],
"socialmedia": [],
"additionalitems": {
"item": [ {
"key": "btosisnumber",
"value": "02086666666"
}],
"tmp": null
},
"groupedadditionalitems": []
}],
"tmp": null
},
"uprn": null,
"lpi": null,
"blpu": null,
"streetdescriptor": null,
"streetinformation": null,
"companyinformation": null,
"classification": null,
"osal2toid": null,
"ositntoid": null,
"ostopotoid": null,
"voactrecord": null,
"voandrrecord": null,
"aposapr": null,
"rmudprn": null,
"utilitiesinformation": null
}],
"relateddata": null,
"groupedrelateddata": []
}]
},
"validateresponse": null,
"verifyresponse": null,
"traceresponse": null
}]
}Sample Directory Enquiry Organisation Lookup XML
The following XML sample demonstrates a request data object containing an organisation and Address.
<!-- request input data - address and telephone -->
<mes:requestdata>
<req:address>
<data:organisation>gb group*</data:organisation>
<data:street/>
<data:town></data:town>
<data:postcode>ch4 9gb</data:postcode>
<data:locality/>
<data:subbuilding/>
<data:building/>
<data:sublocality/>
<data:stateregion/>
<data:countrycode>gbr</data:countrycode>
<data:pobox/>
<data:freeformataddress></data:freeformataddress>
<data:additionalitems tmp="?"></data:additionalitems>
<data:persons tmp="?">
<data:person>
</data:person>
</data:persons>
</req:address>
<req:filters tmp="?"></req:filters>
<req:options></req:options>
</mes:requestdata>{
"customerreference": "test",
"profileguid": "c4915b34-639a-45ab-b6d5-75f61dfe73b9",
"configurationid": "1",
"requestdata": {
"address": {
"town": "chester",
"organisation": "gb g*",
"postcode": "ch4*",
"building": "gb*"
},
"options": {
"offset": "0",
"maxreturn": "10",
"addresssearchlevel": "premise",
"casing": "mixed"
}
}
}
Sample Organisation Lookup Output XML
The following output XML demonstrates the CaptureResponse for the above Organisation UK Telephone Directory lookup.
<!-- telephone component response -->
<mes:captureresponse>
<req:resultstatus>multiple</req:resultstatus>
<req:recordsreturned>3</req:recordsreturned>
<req:moredata>false</req:moredata>
<req:totalrecordcount>3</req:totalrecordcount>
<req:totalpages>1</req:totalpages>
<req:matchscore>0</req:matchscore>
<req:responsecount>0</req:responsecount>
<req:response>
<req:address>
<data:organisation>gb group plc</data:organisation>
<data:street>herons way</data:street>
<data:town>chester</data:town>
<data:postcode>ch4 9gb</data:postcode>
<data:locality>chester business park</data:locality>
<data:buildingname>the foundation</data:buildingname>
<data:stateregion>cheshire</data:stateregion>
<data:additionalitems>
<data:item>
<data:key>btosisnumber</data:key>
<data:value>01244657333</data:value>
</data:item>
</data:additionalitems>
<data:persons/>
</req:address>
<req:address>
.
.
.
</req:address>
<req:address>
.
.
.
</req:response>
</mes:captureresponse>Sample Organisation Lookup Output JSON
{
"profileheader": {
"profileguid": "c4915b34-639a-45ab-b6d5-75f61dfe73b9",
"profilename": "uk telephone number - directory enquiries",
"transactionguid": "858ebd43-037b-466e-b497-74876c408e09",
"transactiontimestamp": 1433341716547,
"profilestatus": "success",
"remarks": null
},
"profileresponsedetails": [ {
"transactionguid": "a2ae771c-7dc2-4a6d-8c06-70f8b11a23ad",
"componentname": "osis - directory enquiry capture service",
"componentstatus": "success",
"componentaction": "directory_enquiry",
"responsetype": "capture",
"notes": "[]",
"invoice": {
"invoicelist": [ {
"invoiceguid": "ff06cde5-7fb1-4493-96d3-c1e3b12fa0dc",
"billinginformationguid": "3e1c4c82-ed38-4bcf-a7bb-f92d26814294",
"datalicencedescription": null,
"billingpoints": 1,
"creditsused": 1,
"datasetinvoices": [ {
"datasetcode": "directory_enquiry",
"billingpoints": 1,
"recordsreturned": 4,
"datalicenceguid": "3e1c4c82-ed38-4bcf-a7bb-f92d26814294"
}]
}],
"tmp": null
},
"captureresponse": {
"resultstatus": "multiple",
"resultstatusdetail": null,
"recordsreturned": 1,
"moredata": false,
"totalrecordcount": 1,
"totalpages": 1,
"matchscore": 0,
"matchlevel": null,
"outputstatus": null,
"fieldstatus": null,
"responsecount": 1,
"response": [ {
"input": null,
"address": [
{
"organisation": "gb group plc",
"street": "herons way",
"town": "chester",
"postcode": "ch4 9gb",
"locality": "chester business park",
"addpoint": null,
"department": "main switchboard",
"subbuilding": null,
"buildingnumber": null,
"buildingname": "gb house kingsfield court",
"buildinggroup": null,
"pobox": null,
"substreet": null,
"sublocality": null,
"stateregion": "cheshire",
"subadministrativearea": null,
"administrativearea": null,
"superadministrativearea": null,
"countrycode": "gbr",
"countryname": null,
"dpszipplus": null,
"formattedaddress": null,
"geographicinformation": null,
"additionalitems": {
"item": [ {
"key": "btosisnumber",
"value": "01244657333"
}],
"tmp": null
},
"groupedadditionalitems": [],
"persons": {
"person": [],
"tmp": null
},
"uprn": null,
"lpi": null,
"blpu": null,
"streetdescriptor": null,
"streetinformation": null,
"companyinformation": null,
"classification": null,
"osal2toid": null,
"ositntoid": null,
"ostopotoid": null,
"voactrecord": null,
"voandrrecord": null,
"aposapr": null,
"rmudprn": null,
"utilitiesinformation": null
}
],
"relateddata": null,
"groupedrelateddata": []
}]
},
"validateresponse": null,
"verifyresponse": null,
"traceresponse": null
}]
}Sample Ambiguous Locality Lookup XML
The following XML sample demonstrates a request data object containing an ambiguous locality in the address.
<!-- request input data - address and telephone -->
<mes:requestdata>
<req:address>
<data:organisation/>
<data:street/>
<data:town>st helens</data:town>
<data:postcode></data:postcode>
<data:locality></data:locality>
<data:subbuilding/>
<data:building></data:building>
<data:sublocality/>
<data:stateregion/>
<data:countrycode>gbr</data:countrycode>
<data:pobox/>
<data:freeformataddress></data:freeformataddress>
<data:additionalitems tmp="?"></data:additionalitems>
<data:persons tmp="?">
<data:person>
<data:lastname>smith</data:lastname>
</data:person>
</data:persons>
</req:address>
<req:filters tmp="?"></req:filters>
<req:options></req:options>
</mes:requestdata>Sample Ambiguous Locality Lookup Output XML
The following output XML demonstrates the CaptureResponse for the above ambiguous locality UK Telephone Directory lookup.
<!-- uk telephone directory execute component response -->
<mes:executecomponentresponse>
<mes:action>os</mes:action>
<mes:completed>true</mes:completed>
<mes:datasetinvoices>
<req:datasetcode>directory_enquiry</req:datasetcode>
<req:billingpoints>0</req:billingpoints>
<req:recordsreturned>0</req:recordsreturned>
</mes:datasetinvoices>
<mes:notes>locality not specific enough</mes:notes>
<mes:captureresponse>
<req:resultstatus>picklist</req:resultstatus>
<req:recordsreturned>2</req:recordsreturned>
<req:moredata>false</req:moredata>
<req:totalrecordcount>2</req:totalrecordcount>
<req:totalpages>1</req:totalpages>
<req:matchscore>0</req:matchscore>
<req:responsecount>2</req:responsecount>
<req:response>
<req:address>
<data:town>ryde</data:town>
<data:locality>st helens</data:locality>
<data:stateregion>isle of wight</data:stateregion>
<data:persons/>
</req:address>
<req:address>
<data:town>st helens</data:town>
<data:stateregion>merseyside</data:stateregion>
<data:persons/>
</req:address>
</req:response>
</mes:captureresponse>
</mes:executecomponentresponse>Error Information
Information on possible error codes is given here: Error Code Information