Matchcode UK Address Integration Guide
This web service guide is recommended for customers looking to use Address Validation using Royal Mail's PAF (Postal Address File), Multiple Residency and Not-Yet-Built.
Other Consumer and Location Intelligence services can also be appended such as the Acorn demographic data and GBG's Location Intelligence file.
This web service also provides access to GBG's Names data which allows our customers to confirm the correct spelling and date of birth of UK Citizens.
Please discuss with your account manager if you would like to use any of these additional datasets.
About This Guide
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
Section 2 of the document gives product specific details regarding the use of the Matchcode Names web service products via IdM.
Please note: Wherever <LatestWSDLVersion> is shown in Example Code below, please replace this with GlobalServices21a.wsdl.
Matchcode Names Web Service Product Information
The Matchcode Names service provides access to UK names information in a similar manner to Matchcode UK Address searching (see Matchcode UK Address Integration Guide)
The Matchcode Names web service products are available via the Identity Management ExecuteCapture web service method.
Input Format
The ExecuteCapture method takes in a ExecuteCaptureRequest data structure, which contains all the information necessary to carry out the request.
Type: ExecuteCaptureRequest
| Field Name | Type | Description |
|---|---|---|
| securityHeader | SecurityHeader | The username and authentication token used to access the system. |
| profileRequest | ProfileRequestCapture | Details of the request |
The SecurityHeader structure holds security data to access products and services in the IdM Platform.
The ProfileRequestCapture structure contains the criteria to identify the target product being called and the search data for the product request.
Within the profileRequest element, the profileGuid element should contain the GUID value listed below:
| Profile | GUID |
|---|---|
| Matchcode Names web service | A86F1483-822B-4CB8-A683-349F54F4A6C6 |
Search Criteria
The address search criteria should be entered into the IdmDataSearchAddress data structure, which is located within the input details as follows:
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → address
The search address object is the same that is used in the Address Lookup request, described here.
The persons criteria should be entered into the persons property of the address, multiple persons can be specified with multiple instances of the IdmDataPerson data structure. When this criteria is specified, only the people at the matched address which match the persons criteria are returned. If no persons critieria is specified, then all the people are returned for the address which has been matched to the input address.
While multiple person objects can be specified for the address, only the first person object is used and the rest are ignored. This does not however mean that only one specific person can be searched for, because of the way that the person fields are treated, as described below.
When a person object is used in the search criteria, the last name must be provided. All other person fields are optional, and are treated as wild cards when not provided. The date of birth field however is not applicable to this service and is ignored. This behaviour allows more or less specific searches to be done as required, by simply adding or removing person fields.
Additional Request Options
The additional search options, used for configuring options such as casing or transliteration of output results, can be set in the IdmRequestOptions structure located in the ProfileRequestCaptureData.options property.
Additional Return Data
Additional data can be returned, or excluded from being returned, for each address by providing one or more values in the IdmRequestOption.relatedDataItems property.
Note: For each value provided, the corresponding data is returned, and the corresponding additional data for all the values not provided are not returned. So, for example, if OSLAUA is specified as a relatedDataItem, then the country code, udprn, geocode data (easting, northing, latitude, longitude) and person data (title, first, middle, last names, gender, date-of-birth) will no longer be returned by default; those fields must then be explicitly also requested as relatedDataitems.
The following values are supported by this service.
| Key Mnemonic | Description | Returned By Default | Required subscription | Returned as |
|---|---|---|---|---|
| COUNTRYCODE | Country code | Yes | PAF | countryCode |
| UDPRN | PAF unique delivery point reference number | Yes | PAF | rmUDPRN |
| EFORENAME | Person first name | Yes | PAF+Names | firstname |
| EMIDNAME | Person middle name(s) | Yes | PAF+Names | middlename |
| ESURNAME | Person last name | Yes | PAF+Names | lastname |
| ETITLE | Person title | Yes | PAF+Names | title |
| EGENDER | Person gender | Yes | PAF+Names | gender |
| EDOB | Person date of birth | Yes | PAF+Names | dateOfBirth |
| PCNORTH | 1m grid northing | Yes | PAF | northing |
| PCEAST | 1m grid easting | Yes | PAF | easting |
| LATITUDE | World geodetic standard 1984 datum latitude | Yes | PAF | latitude |
| LONGITUDE | World geodetic standard 1984 datum longitude | Yes | PAF | longitude |
| OSLAUA | Local authority district Code | No | PAF+Names | OSLAUA |
Sample Options XML
<req:options>
<req:addressenvelopeformat>a3tcp</req:addressenvelopeformat>
<req:relateddataitems>
<data:key>udprn</data:key>
</req:relateddataitems>
<req:offset>0</req:offset>
<req:maxreturn>100</req:maxreturn>
<req:casing>mixed</req:casing>
</req:options>Additional Request Datasets
Data from additional datasets can be enabled or disabled for an address search, by populating the ProfileRequestCaptureData.additionalData property with key-value pairs from the applicable list table below. To use a particular dataset, the user must be subscribed to the dataset.
This information should be entered into the IdmDataArrayAdditionalData data structure, which is located within the input details as follows:
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → additionalData
| Key Mnemonic | Key Value | Description |
|---|---|---|
| MULTI_OCC | "Yes" or "No" | Request Multiple Occupancy information to be returned |
| MULTI_RES | "Yes" or "No" | Request Multiple Residency information to be returned |
| NOT_YET_BUILT | "Yes" or "No" | Request Not Yet Built information to be returned |
| ACORN | "Yes" or "No" | Request Acorn consumer classification information to be returned |
| LOC_INT | "Yes" or "No" | Request Location Intelligence information to be returned |
| PREMISE_GEOCODE | "Yes" or "No" | Request Premise Level Geocode information to be returned |
Each dataset, when enabled, supports a set of values which can be used in the related data items property of the request options, these values are listed below.
Multi Occupancy
| MOI | Multi occupancy indicator | Yes |
| Key Mnemonic | Description | Returned By Default |
|---|
Multiple Residency
| UMRRN | Unique multiple residence reference number | Yes |
| OWNINGUDPRN | UDPRN of owning delivery point | Yes |
| OWNINGAK | Address key of owning delivery point | Yes |
| OWNINGOK | Organisation key of owning delivery point | Yes |
| OWNINGAKOK | Address and organisation key of owning delivery point | Yes |
| PCTYPE | Large or small user indicator | Yes |
| Key Mnemonic | Description | Returned By Default |
|---|
Not Yet Built
| NOTYETBUILT | Flag set to ‘Y’ for all Not Yet Built addresses | Yes |
| NYB_UDPRN | Unique delivery point reference number | Yes |
| Key Mnemonic | Description | Returned By Default |
|---|
ACORN
| ACORNCOD | ACORN classification | Yes |
| ACATNAME | ACORN category | Yes |
| AGRPNAME | ACORN group | Yes |
| ATYPNAME | ACORN type | Yes |
| Key Mnemonic | Description | Returned By Default |
|---|
Location Intelligence
The Location Intelligence dataset is detailed here.
Premise Level Geocodes
The Premise Level Geocodes dataset is detailed here.
Address Filters
Addresses which have been found by the web service, which match a particular kind of address, can be filtered out from the search results by using the address filters functionality described here.
Output Format
The results of the Matchcode Names web service 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]
PAF Address Elements
The returned address will include address elements from the Royal Mail Postcode Address File (PAF), as well as non-PAF elements and information on persons at the address.
Below is a list of specifcally PAF address elements
| PAF Field | Output Field: IdmDataAddress |
|---|---|
| Organisation | organisation |
| Department | department |
| Sub Building | subBuilding |
| Building Name | buildingName |
| Building Number | buildingNumber |
| PO Box | poBox |
| Thorofare | street |
| Dependent Thorofare | subStreet |
| Dependent Locality | locality |
| Double Dependant Locality | sublocality |
| Post Town | town |
| County | stateRegion |
| Postal Code | postCode |
Additional Items
Additional data from a search may be returned in the additionalItems or the groupedAdditionalItems of the IdmDataAddress.
Below is a list of possible additional data fields for this service. The fields returned for a particular search depends on the related data items specified in the request, the additional datasets enabled in the request and the data available for the matched addresses.
| Name | Description | Requirements for Output |
|---|---|---|
| NOTYETBUILT | Not Yet Built Indicator (Y/N) | NOT_YET_BUILT dataset enabled in request |
| UMRRN | Unique Multiple Residence Reference Number | MULTI_RES dataset enabled in request |
| OWNINGUDPRN | Unique Delivery Point Reference Number of owning Delivery Point | MULTI_RES dataset enabled in request |
| OWNINGAK | Address Key of owning Delivery Point | MULTI_RES dataset enabled in request |
| OWNINGOK | Organisation Key of owning Delivery Point | MULTI_RES dataset enabled in request |
| OWNINGAKOK | Combined Address and Organisation Key of owning Delivery Point | MULTI_RES dataset enabled in request |
| MOI | Multiple Occupancy Indicator | MULTI_OCC dataset enabled in request |
| ACORNCLASS | Acorn Classification | ACORN dataset enabled in request |
| ACORNCATE | Acorn Category | ACORN dataset enabled in request |
| ACORNGROU | Acorn Group | ACORN dataset enabled in request |
| ACORNTYPE | Acorn Type | ACORN dataset enabled in request |
| OSLAUA | Local authority district Code | OSLAUA in additional return data |
Example Requests & Responses
Example Requests
SOAP
<soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:a="http://gbworld.gb.co.uk/idm-globalservices/messages/<latestwsdlversion>/"
xmlns:head="http://gbworld.gb.co.uk/types/header/"
xmlns:req="http://gbworld.gb.co.uk/types/core/request/"
xmlns:data="http://gbworld.gb.co.uk/types/core/data/">
<soapenv:header/>
<soapenv:body>
<a:executecapturerequest>
<a:securityheader>
<head:authenticationtoken>c18ab65d-85a0-4c48-81a9-c5e23058c819</head:authenticationtoken>
<head:username>censored</head:username>
</a:securityheader>
<a:profilerequest>
<req:customerreference>sample names lookup</req:customerreference>
<req:profileguid>a86f1483-822b-4cb8-a683-349f54f4a6c6</req:profileguid>
<req:configurationid>1</req:configurationid>
<req:requestdata>
<req:address>
<data:postcode>ch49gb</data:postcode>
</req:address>
<req:filters tmp="?"/>
<req:options>
<req:addressenvelopeformat>a4p</req:addressenvelopeformat>
<req:offset>0</req:offset>
<req:maxreturn>50</req:maxreturn>
<req:transliteration>native</req:transliteration>
<req:countrycodeformat>iso3</req:countrycodeformat>
</req:options>
<req:additionaldata tmp="?"/>
</req:requestdata>
</a:profilerequest>
</a:executecapturerequest>
</soapenv:body>
</soapenv:envelope>REST
{
"customerreference":"test",
"profileguid":"a86f1483-822b-4cb8-a683-349f54f4a6c6",
"configurationid":"1",
"requestdata":{
"address":{
"postcode":"ch49gb"
},
"options":{
"offset":"0",
"maxreturn":"10"
},
"additionaldata":{
}
}
}Example Responses
SOAP
<soap-env:envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
<soap-env:header/>
<soap-env:body>
<ns5:executecaptureresponse xmlns:ns5="http://gbworld.gb.co.uk/idm-globalservices/messages/<latestwsdlversion>/"
xmlns:alu="http://gbworld.gb.co.uk/types/core/request/alu/"
xmlns:common="http://gbworld.gb.co.uk/types/common/"
xmlns:comp="http://gbworld.gb.co.uk/types/component/"
xmlns:data="http://gbworld.gb.co.uk/types/core/data/"
xmlns:datatypes="http://gbworld.gb.co.uk/types/datatypes/"
xmlns:faults="http://gbworld.gb.co.uk/types/faults/"
xmlns:head="http://gbworld.gb.co.uk/types/header/"
xmlns:ns8="http://gbworld.gb.co.uk/types/core/data/trace/"
xmlns:prop="http://gbworld.gb.co.uk/idm-core/component/properties/"
xmlns:req="http://gbworld.gb.co.uk/types/core/request/"
xmlns:ver="http://gbworld.gb.co.uk/types/core/request/verify/">
<ns5:securityheader>
<head:authenticationtoken xmlns:xsi="http://www.w3.org/2001/xmlschema-instance">
1273f4fa-3ae7-4742-a0c6-626d006a445a
</head:authenticationtoken>
<head:authenticationtime xmlns:xsi="http://www.w3.org/2001/xmlschema-instance">
2014-02-14t13:05:11.000z
</head:authenticationtime>
<head:sessionexpirytime xmlns:xsi="http://www.w3.org/2001/xmlschema-instance">
2014-02-14t13:35:20.449z
</head:sessionexpirytime>
</ns5:securityheader>
<ns5:transactionguid>8f9f9258-e772-45fc-b486-7f09fd3f067b</ns5:transactionguid>
<ns5:profileresponse>
<req:profileheader>
<req:profileguid>a86f1483-822b-4cb8-a683-349f54f4a6c6</req:profileguid>
<req:profilename>matchcode names</req:profilename>
<req:transactionguid>8f9f9258-e772-45fc-b486-7f09fd3f067b</req:transactionguid>
<req:transactiontimestamp>2014-02-14t13:05:20.537z</req:transactiontimestamp>
<req:profilestatus>success</req:profilestatus>
</req:profileheader>
<req:profileresponsedetails>
<req:transactionguid>87f581b6-5ec4-4f5d-9335-245b95c33b05</req:transactionguid>
<req:componentname>matchcode edited electoral roll names</req:componentname>
<req:componentstatus>success</req:componentstatus>
<req:componentaction>register</req:componentaction>
<req:responsetype>capture</req:responsetype>
<req:notes>[]</req:notes>
<req:invoice>
<req:invoicelist>
<req:invoiceguid>082bb684-3ed6-4c2b-9422-0959826dabd1</req:invoiceguid>
<req:billinginformationguid>ccb1c022-bf7c-4c71-b445-710110fa0fc7
</req:billinginformationguid>
<req:billingpoints>1</req:billingpoints>
<req:creditsused>1</req:creditsused>
<req:datasetinvoices>
<req:datasetcode>names</req:datasetcode>
<req:billingpoints>1</req:billingpoints>
<req:recordsreturned>1</req:recordsreturned>
<req:datalicenceguid>ccb1c022-bf7c-4c71-b445-710110fa0fc7</req:datalicenceguid>
</req:datasetinvoices>
</req:invoicelist>
</req:invoice>
<req: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:matchlevel>postcode</req:matchlevel>
<req:outputstatus>notmatched</req:outputstatus>
<req:fieldstatus>55555555</req:fieldstatus>
<req:responsecount>1</req:responsecount>
<req:response>
<req:address>
<data:organisation>gb group plc</data:organisation>
<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:dpszipplus>1ar</data:dpszipplus>
<data:formattedaddress>gb group plc,the foundation,herons way, chester business park,chester cheshire,ch4 9gb
</data:formattedaddress>
<data:persons>
<data:person>
<data:title>ms.</data:title>
<data:gender>female</data:gender>
<data:firstname>abigail</data:firstname>
<data:lastname>green</data:lastname>
</data:person>
<data:person>
<data:title>mr.</data:title>
<data:gender>male</data:gender>
<data:firstname>adam</data:firstname>
<data:lastname>green</data:lastname>
</data:person>
</data:persons>
</req:address>
</req:response>
</req:captureresponse>
</req:profileresponsedetails>
</ns5:profileresponse>
</ns5:executecaptureresponse>
</soap-env:body>
</soap-env:envelope>REST
{
"profileheader":{
"profileguid":"a86f1483-822b-4cb8-a683-349f54f4a6c6",
"profilename":"matchcode names",
"transactionguid":"7e3b1a9c-4c0f-4253-9f32-7532282ad2c0",
"transactiontimestamp":1433410021843,
"profilestatus":"success",
"remarks":null
},
"profileresponsedetails":[
{
"transactionguid":"b4d1a4e0-f3e8-4719-895e-bfaa496cc55e",
"componentname":"matchcode edited electoral roll names",
"componentstatus":"success",
"componentaction":"verify",
"responsetype":"capture",
"notes":"[]",
"invoice":{
"invoicelist":[
{
"invoiceguid":null,
"billinginformationguid":"f0cf11e6-fc43-41e3-83d4-6086fd26023a",
"datalicencedescription":null,
"billingpoints":0,
"creditsused":0,
"datasetinvoices":[
]
},
{
"invoiceguid":"b105a327-6d55-4d2a-ab10-6fdbe599f98d",
"billinginformationguid":"ccb1c022-bf7c-4c71-b445-710110fa0fc7",
"datalicencedescription":null,
"billingpoints":1,
"creditsused":1,
"datasetinvoices":[
{
"datasetcode":"names",
"billingpoints":1,
"recordsreturned":1,
"datalicenceguid":"ccb1c022-bf7c-4c71-b445-710110fa0fc7"
}
]
},
{
"invoiceguid":"816fa32b-4bfe-44ce-a2cd-d4b018ea62a3",
"billinginformationguid":"1e409557-6178-4970-a55f-8da336a12410",
"datalicencedescription":null,
"billingpoints":1,
"creditsused":1,
"datasetinvoices":[
{
"datasetcode":"multi_res",
"billingpoints":1,
"recordsreturned":1,
"datalicenceguid":"1e409557-6178-4970-a55f-8da336a12410"
}
]
},
{
"invoiceguid":"c00ef75e-1405-403d-9734-dd2acbb544cf",
"billinginformationguid":"21ac03a7-c59b-4446-abf0-0e02b8d72be8",
"datalicencedescription":null,
"billingpoints":1,
"creditsused":1,
"datasetinvoices":[
{
"datasetcode":"not_yet_built",
"billingpoints":1,
"recordsreturned":1,
"datalicenceguid":"21ac03a7-c59b-4446-abf0-0e02b8d72be8"
}
]
},
{
"invoiceguid":null,
"billinginformationguid":"4e4cc906-7c21-4118-8fb6-0df7f4164b38",
"datalicencedescription":null,
"billingpoints":0,
"creditsused":0,
"datasetinvoices":[
]
}
],
"tmp":null
},
"captureresponse":{
"resultstatus":"single",
"resultstatusdetail":null,
"recordsreturned":1,
"moredata":false,
"totalrecordcount":1,
"totalpages":1,
"matchscore":0,
"matchlevel":"postcode",
"outputstatus":"notmatched",
"fieldstatus":"55555555",
"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":null,
"subbuilding":null,
"buildingnumber":null,
"buildingname":"the foundation",
"buildinggroup":null,
"pobox":null,
"substreet":null,
"sublocality":null,
"stateregion":"cheshire",
"subadministrativearea":null,
"administrativearea":null,
"superadministrativearea":null,
"countrycode":"gbr",
"countryname":null,
"dpszipplus":"1ar",
"formattedaddress":"gb group plc,the foundation,herons way chester business park,chester,cheshire,ch4 9gb",
"geographicinformation":{
"easting":"340009",
"northing":"363192",
"latitude":"53.1624546529",
"longitude":"-2.8987262198",
"status":null,
"level":null,
"distance":null,
"radius":null
},
"additionalitems":{
"item":[
{
"key":"datasource",
"value":"names"
}
],
"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
}
]
}