> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Web Service Integration Guide

> **Please note that this is a legacy product in retirement.**

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](/our-services/legacy-products/matchcode/general-information/integration-fundamentals)

The main body of this document gives product specific details regarding the use of the Address Web Service products via IdM.

**Please note:** Wherever (LatestWSDLVersion) is shown in Example Code below, please replace this with GlobalServices21a.wsdl.

## Address Web Service Product Information

The UK Address web service products are available via the Identity Management **ExecuteCapture** web service method.

### Basic Name and Address Capture

## Method: ExecuteCapture

The **ExecuteCapture** method is used to access the GBG Customer Registration products and services by invoking the corresponding profile.

## Input Details

**Type: ExecuteCaptureRequest**

| Field Name     | Type                                                                                                                           | Description                                                      |
| :------------- | :----------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| securityHeader | [SecurityHeader](/our-services/legacy-products/matchcode/general-information/idm-data-structures#securityheader)               | The username and authentication token used to access the system. |
| profileRequest | [ProfileRequestCapture](/our-services/legacy-products/matchcode/general-information/idm-data-structures#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. In the profileRequest element, the **profileGuid** should be specified as:

| Profile              | GUID                                 |
| :------------------- | :----------------------------------- |
| ddress Premise       | 6C49BC44-C104-41b2-BB62-2AE45A09DD54 |
| Address Street Level | C6356DD8-1CBA-4371-BE94-D5E08F1C777E |

## Output Details

The **ExecuteCaptureResponse** structure contains the results of an capture query. The response contains the authentication token to be passed into subsequent web service calls. The latest authentication token should always be passed into service calls.

**Type: ExecuteCaptureResponse**

| Field Name             | Type                                                                                                                             | Description                                     |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------- |
| securityHeaderResponse | [SecurityHeaderResponse](/our-services/legacy-products/matchcode/general-information/idm-data-structures#securityheaderresponse) | Authentication information for subsequent calls |
| transactionGuid        | String                                                                                                                           | Unique transaction reference                    |
| profileResponse        | [ProfileResponse](/our-services/legacy-products/matchcode/general-information/idm-data-structures#profileresponse)               | Response to the query                           |

The **ProfileResponse** structure contains the results for an operation performed against a profile.

**Type: ProfileResponse**

| Field Name            | Type                                                                                                                             | Description                                                   |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| ProfileResponseHeader | [ProfileResponseHeader](/our-services/legacy-products/matchcode/general-information/idm-data-structures#profileresponseheader)   | Contains the Profile information for the results of the query |
| profileResponses      | [ProfileResponseDetails](/our-services/legacy-products/matchcode/general-information/idm-data-structures#profileresponsedetails) | Response data to the query                                    |

The **ProfileResponseDetails** structure contains the results for an operation performed against a product/data service in the **Profile**. It is possible to call multiple products in a single profile; in this case there will be multiple **ProfileResponseDetails** structures, one for each product.

**Type: ProfileResponseDetails**

| Field Name       | Type                                                                                                                     | Description                                                                            |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| transactionGuid  | String                                                                                                                   | Unique transaction identifier for the component e.g. Address Lookup component          |
| componentName    | String                                                                                                                   | Name of the component                                                                  |
| componentStatus  | Enum                                                                                                                     | SUCCESS, FAILURE, INSUFFICIENTCRITERIA, NA                                             |
| componentAction  | String                                                                                                                   | Component Action                                                                       |
| responseType     | Enum                                                                                                                     | CAPTURE                                                                                |
| invoice          | [DataLicenceInvoice](/our-services/legacy-products/matchcode/general-information/idm-data-structures#datalicenceinvoice) | List of charges for the query                                                          |
| captureResponse  | [CaptureResponse](/our-services/legacy-products/matchcode/general-information/idm-data-structures#captureresponse)       | Data from a component returning data e.g. Address lookup data                          |
| validateResponse | ValidateResponse                                                                                                         | Data from a component returning validation responses e.g. Telephone Validation service |

The **CaptureResponse** structure contains response records for a particular component/product. The data is held in a standard format across all products. The data structure is a flexible set of arrays designed to represent the data in a way that reflects the records in context of the search. The arrangement of the data will depend on the product in question. For more information on the layout of the response data please refer to the corresponding product documentation.

**Type: CaptureResponse**

| Field Name       | Type                                                                                                                       | Description                                                        |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
| resultStatus     | Enum                                                                                                                       | NA, INSUFFICIENTCRITERIA, NONE, SINGLE, MULTIPLE, PICKLIST, VERIFY |
| recordsReturned  | Int                                                                                                                        | Number individual of records returned e.g. number of addresses     |
| moreData         | Boolean                                                                                                                    | More data on the server                                            |
| totalRecordCount | Int                                                                                                                        | Total records from the query                                       |
| totalPages       | Int                                                                                                                        | Pagination - Total pages                                           |
| responseCount    | Int                                                                                                                        | Number of groups of responses returned                             |
| response         | [CaptureResponseData](/our-services/legacy-products/matchcode/general-information/idm-data-structures#captureresponsedata) | Response data                                                      |

The **ValidateResponse** structure contains response records for a particular component/product. The data is held in a standard format across all products. For more information on the layout of the response data please refer to the corresponding product documentation.

**Type: ValidateResponse**

| Field Name      | Type                 | Description                                                        |
| :-------------- | :------------------- | :----------------------------------------------------------------- |
| resultStatus    | Enum                 | NA, INSUFFICIENTCRITERIA, NONE, SINGLE, MULTIPLE, PICKLIST, VERIFY |
| recordsReturned | Int                  | Number individual of records returned e.g. number of addresses     |
| responseCount   | Int                  | Number of group of response returned                               |
| response        | ValidateResponseData | Response data                                                      |

## Sample XML

**Sample request:**

```java theme={null}
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:mes="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/" 
       xmlns:xsi="xsi">
      <soapenv:Header/>
      <soapenv:Body>
       <mes:ExecuteCaptureRequest>
        <mes:securityHeader>
         <head:username>user@domain.com</head:username>
        </mes:securityHeader>
        <mes:profileRequest>
         <req:customerReference>Test</req:customerReference>
         <req:profileGuid>6C49BC44-C104-41b2-BB62-2AE45A09DD54</req:profileGuid>
         <req:requestData>
            <req:address>
             <data:town>CHESTER</data:town>
             <data:postCode>CH49GB</data:postCode>
             <data:building>*</data:building>
            </req:address>
            <req:filters/>
            <req:options>
             <req:addressEnvelopeFormat>A4P</req:addressEnvelopeFormat>
             <req:relatedDataItems tmp="?">
              <!--Zero or more repetitions:-->
              <data:key>UBID</data:key>
             </req:relatedDataItems>
             <req:offset>0</req:offset>
             <req:maxReturn>100</req:maxReturn>
             <req:addressSearchLevel>PREMISE</req:addressSearchLevel>
             <req:casing>MIXED</req:casing>
            </req:options>
            <req:additionalData/>
         </req:requestData>
        </mes:profileRequest>
       </mes:ExecuteCaptureRequest>
      </soapenv:Body>
   </soapenv:Envelope>
```

```json theme={null}
{
    "customerReference": "Test",
    "profileGuid": "6C49BC44-C104-41b2-BB62-2AE45A09DD54",
    "configurationId": "1",
    "requestData": {
      "address": {
        "town": "CHESTER",
        "postCode": "CH49GB",
        "building": "*"
      },
      "options": {
        "addressEnvelopeFormat": "A4P",
        "relatedDataItems":{"key":["UBID"]},
        "offset": "0",
        "maxReturn": "100",
        "addressSearchLevel": "PREMISE",
        "casing": "MIXED"
      }
    }
}
```

**Sample response:**

```xml theme={null}
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
              <SOAP-ENV:Header/>
              <SOAP-ENV:Body>
               <mes:ExecuteCaptureResponse xmlns:mes="http://gbworld.gb.co.uk/idm-globalservices/messages/<LatestWSDLVersion>/"
                 xmlns:alu="http://gbworld.gb.co.uk/types/core/request/alu/" xmlns:billingTypes="http://gbworld.gb.co.uk/types/billing/" 
                 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: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/">
                <mes:securityHeader>
                 <head:authenticationToken xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                 <head:authenticationTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                   2012-12-17T20:27:21.879Z</head:authenticationTime>
                 <head:sessionExpiryTime xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                </mes:securityHeader>
                <mes:transactionGuid>0E64D43B-378D-40CB-9DD9-89C41A4D9A8A</mes:transactionGuid>
                <mes:profileResponse>
                 <req:profileHeader>
                    <req:profileGuid>6C49BC44-C104-41b2-BB62-2AE45A09DD54</req:profileGuid>
                    <req:profileName>Address Lookup - Fixed Field</req:profileName>
                    <req:transactionGuid>0E64D43B-378D-40CB-9DD9-89C41A4D9A8A</req:transactionGuid>
                    <req:transactionTimeStamp>2012-12-17T20:27:21.610Z</req:transactionTimeStamp>
                    <req:profileStatus>SUCCESS</req:profileStatus>
                 </req:profileHeader>
                 <req:profileResponses>
                    <req:profileResponse>
                     <req:transactionGuid>86CA24C8-51CA-4E09-8785-473693BD3147</req:transactionGuid>
                     <req:componentName>NR Address Lookup</req:componentName>
                     <req:componentStatus>SUCCESS</req:componentStatus>
                     <req:componentAction>NR</req:componentAction>
                     <req:responseType>CAPTURE</req:responseType>
                     <req:notes>[]</req:notes>
                     <req:invoice>
                      <req:invoiceList>
                       <req:invoiceGuid>503656F9-2BB3-4908-9965-36456F77B024</req:invoiceGuid>
                       <req:billingInformationGuid>376B7A97-C25B-4d14-8AB1-64CD874AEECE</req:billingInformationGuid>
                       <req:billingPoints>1</req:billingPoints>
                       <req:dataSetInvoices>
                          <req:dataSetCode>PAF</req:dataSetCode>
                          <req:billingPoints>1</req:billingPoints>
                          <req:recordsReturned>1</req:recordsReturned>
                          <req:dataLicenceGuid>376B7A97-C25B-4d14-8AB1-64CD874AEECE</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:responseCount>1</req:responseCount>
                      <req:response>
                       <req:addresses>
                          <data: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:dpsZipPlus>1AR</data:dpsZipPlus>
                           <data:formattedAddress>Gb Group Plc,The Foundation,Herons Way, Chester Business Park,Chester Cheshire,CH4 9GB</data:formattedAddress>                            <data:additionalItems>
                            <data:item>
                             <data:key>UBID</data:key>
                             <data:value>CH049GB11A</data:value>
                            </data:item>
                           </data:additionalItems>
                           <data:persons/>
                          </data:address>
                       </req:addresses>
                      </req:response>
                     </req:captureResponse>
                    </req:profileResponse>
                 </req:profileResponses>
                </mes:profileResponse>
               </mes:ExecuteCaptureResponse>
              </SOAP-ENV:Body>
           </SOAP-ENV:Envelope>
```

```json theme={null}
{
   "profileHeader":    {
      "profileGuid": "C6356DD8-1CBA-4371-BE94-D5E08F1C777E",
      "profileName": "Address Street Level - Web Service",
      "transactionGuid": "5D4B9677-A109-40B2-A35B-C92E5C70168F",
      "transactionTimeStamp": 1433332665130,
      "profileStatus": "SUCCESS",
      "remarks": null
   },
   "profileResponseDetails": [   {
      "transactionGuid": "8E9CE0BD-70C8-482F-9B74-9472E32F9F7A",
      "componentName": "Accelerator Address",
      "componentStatus": "SUCCESS",
      "componentAction": "NR",
      "responseType": "CAPTURE",
      "notes": "[]",
      "invoice":       {
         "invoiceList": [         {
            "invoiceGuid": "B2DAF313-A4C6-49E6-83D0-F37B820A3E7A",
            "billingInformationGuid": "88176B02-9CE0-431d-8913-43A138AF64B8",
            "dataLicenceDescription": null,
            "billingPoints": 1,
            "creditsUsed": 1,
            "dataSetInvoices": [            {
               "dataSetCode": "PAF_PARTIAL",
               "billingPoints": 1,
               "recordsReturned": 1,
               "dataLicenceGuid": "88176B02-9CE0-431d-8913-43A138AF64B8"
            }]
         }],
         "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": "Kingsfield Court",
               "town": "CHESTER",
               "postCode": "CH4 9GB",
               "locality": "Chester Business Park",
               "addPoint": null,
               "department": null,
               "subBuilding": null,
               "buildingNumber": null,
               "buildingName": null,
               "buildingGroup": null,
               "poBox": null,
               "subStreet": null,
               "subLocality": null,
               "stateRegion": "Cheshire",
               "subAdministrativeArea": null,
               "administrativeArea": null,
               "superAdministrativeArea": null,
               "countryCode": "GBR",
               "countryName": null,
               "dpsZipPlus": null,
               "formattedAddress": "Gb Group Plc,The Foundation,Herons Way, Chester Business Park,Chester Cheshire,CH4 9GB",
               "geographicInformation":                {
                  "easting": "340000",
                  "northing": "363100",
                  "latitude": " 53.161350",
                  "longitude": " -2.897495",
                  "status": null,
                  "level": null,
                  "distance": null,
                  "radius": null
               },
               "additionalItems":                {
                  "item": [],
                  "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
   }]
}
```

### Address Capture - Search Criteria

The address search criteria should be entered into the [IdmDataSearchAddress](/our-services/legacy-products/matchcode/general-information/idm-data-structures#idmdataaddress) data structure, which is located within the input details as follows:

**ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → IdmDataSearchAddress**

## Radius Search Criteria

Address Web Service supports radius searching, where a match is made for premises within a specified radius of a given point. To trigger a radius search values must be provided in the [IdmDataGeographic](/our-services/legacy-products/matchcode/general-information/idm-data-structures#idmdatageographic) structure of the search address. The easting and northing values should be specified to 5-digit accuracy.

## Additional Search Criteria

Additional information can be searched upon by providing the key value pairs specified below to the **IdmDataSearchAddress.additionalItems** property. For example, if you require to search on Royal Mail Mailsort code the key 'MSRN' and the mailsort value should be provided.

Below is a list of searchable related fields:

| Key Mnemonic | Description                |
| :----------- | :------------------------- |
| AKEY         | 17 Digit Addresskey        |
| AREA         | Local Authority Area Code  |
| EAST         | Easting                    |
| MSRN         | New Mailsort               |
| MSRO         | Old Mailsort               |
| NHSC         | DHA Code                   |
| NRTH         | Northing                   |
| PABR         | Postal Address Book Region |
| WARD         | Local Authority Ward Code  |

Below is a list of additional Royal Mail PAF specific searchable address elements:

| Key Mnemonic | Description               |
| :----------- | :------------------------ |
| BNAM         | Building Name             |
| DDLO         | Double Dependant Locality |
| DEPT         | Department                |
| DPLO         | Dependent Locality        |
| DPTH         | Dependent Thorofare       |

## Sample Search XML

```xml theme={null}
<req:address>
   <!--Optional:-->
   <data:organisation/>
   <data:street/>
   <data:town/>
   <data:postCode>CH49GB</data:postCode>
   <data:locality/>
   <data:subBuilding/>
   <data:building>GB House</data:building>
   <data:subLocality/>
   <data:stateRegion/>
   <data:countryCode>GBR</data:countryCode>
   <data:poBox/>
   <data:freeFormatAddress>CH49GB, GB*</data:freeFormatAddress>
   <data:geographicInformation>
      <data:easting/>
      <data:northing/>
      <data:latitude/>
      <data:longitude/>
      <data:radius>
         <data:unit/>
         <data:distance>0.0</data:distance>
      </data:radius>
   </data:geographicInformation>
   <data:additionalItems tmp="?">
      <data:item>
         <data:key/>
         <data:value/>
      </data:item>
   </data:additionalItems>
</req:address>
```

### Additional Execution Options

Configuration options for the GB Address Web Service search can be set in the [IdmRequestOptions](/our-services/legacy-products/matchcode/general-information/idm-data-structures#idmrequestoptions) structure located in the **ProfileRequestCaptureData.options** property.

|    |                                                                        |
| :- | :--------------------------------------------------------------------- |
|    | Extensible array of key value pairs for future additional conversation |

## Additional Return Data

Additional data can be returned for each address by providing one of the following values to the **IdmRequestOption.relatedDataItems** property (See section 2.2.3 for an example):

| Key Mnemonic | Description                |
| :----------- | :------------------------- |
| AKEY         | 17 Digit Addresskey        |
| AREA         | Local Authority Area Code  |
| EAST         | Easting                    |
| INCO         | Incode Only                |
| MSRN         | New Mailsort               |
| MSRO         | Old Mailsort               |
| NRTH         | Northing                   |
| OUTC         | Outcode Only               |
| PABR         | Postal Address Book Region |
| WARD         | Local Authority Ward Code  |

## Envelope Format

Address web Service provides the option to return each address as it would appear on an envelope.

The **IdmRequestOptions.addressEnvelopeFormat** property allows you to specify how this should data should be formatted. The following are valid configuration options:

| Format Code | Description                                                    |
| :---------- | :------------------------------------------------------------- |
| A4P         | Four address lines and postcode                                |
| A5P         | Five address lines and postcode                                |
| A6P         | Six address lines and postcode                                 |
| A2TCP       | Two address lines, town, county and postcode                   |
| A3TCP       | Three address lines, town, county and postcode                 |
| A4TCP       | Four address lines, town, county and postcode                  |
| NA4P        | Name, four address lines and postcode                          |
| NA5P        | Name, five address lines and postcode                          |
| NA6P        | Name, six address lines and postcode                           |
| NA2TCP      | Name, two address lines, town, county and postcode             |
| NA3TCP      | Name, three address lines, town, county and postcode           |
| NA4TCP      | Name, four address lines, town, county and postcode            |
| A4P-B       | Four address lines without business                            |
| A4TCP-B     | Four address lines, town, county and postcode without business |
| PAF         | All address elements                                           |

## Sample Options XML

```xml theme={null}
<req:options>
  <req:addressEnvelopeFormat>A4P</req:addressEnvelopeFormat>
  <req:relatedDataItems tmp="?">
     <data:key>UBID</data:key>
  </req:relatedDataItems>
  <req:offset>0</req:offset>
  <req:maxReturn>100</req:maxReturn>
  <req:addressSearchLevel>PREMISE</req:addressSearchLevel>
  <req:casing>MIXED</req:casing>
</req:options>
```

### Output Format

The results of the Matchcode UK Address Web Service search are returned in a [ProfileResponseDetails](/our-services/legacy-products/matchcode/general-information/idm-data-structures#profileresponsedetails) structure with a **ProfileResponseDetail.responseType** of 'CAPTURE'.

The **ProfileResponseDetails** structure contains a single [CaptureResponse](/our-services/legacy-products/matchcode/general-information/idm-data-structures#captureresponse) data structure which holds an array of [IdmDataAddress](/our-services/legacy-products/matchcode/general-information/idm-data-structures#idmdataaddress) records containing the returned address data.

**ExecuteCaptureResponse > ProfileResponse \[0] > ProfileResponseDetails \[0] > CaptureResponse > CaptureResponseData > IdmDataAddress \[n]**

## Sample Output XML

```xml theme={null}
<req:response>
  <req:addresses>
     <data:address>
        <data:organisation>GB GROUP PLC</data:organisation>
        <data:street>KINGSFIELD COURT</data:street>
        <data:town>CHESTER</data:town>
        <data:postCode>CH4 9GB</data:postCode>
        <data:locality>CHESTER BUSINESS PARK</data:locality>
        <data:buildingName>GB HOUSE</data:buildingName>
        <data:stateRegion>CHESHIRE</data:stateRegion>
        <data:dpsZipPlus>1AR</data:dpsZipPlus>
        <data:formattedAddress>GB Group Plc,GB House  Kingsfield Court,Chester Business Park,CHESTER Cheshire,CH4 9GB</data:formattedAddress>
        <data:additionalItems>
           <data:item>
              <data:key>UBID</data:key>
              <data:value>CH049GB11A</data:value>
           </data:item>
        </data:additionalItems>
        <data:persons/>
     </data:address>
  </req:addresses>
</req:response>
```

### IdM to Royal Mail PAF

The IdM web services provide the address format in a generic international format. The GB Address Web Service product allows address searching capability on UK based addresses. The mapping between the generic international address structure of IdM web service and the Royal Mail Postal Address File (PAF) is detailed below:

**Data Mapping: IdmDataSearchAddress → Royal Mail PAF → IdmDataAddress**

| Input Field: IdmDataSearchAddress | PAF Field                 | PAF Field Code | Output Field: IdmDataAddress |
| :-------------------------------- | :------------------------ | :------------- | :--------------------------- |
| organisation                      | Organisation              | ORGN           | organisation                 |
| department                        | Department                | DEPT           | department                   |
| subBuilding                       | Sub Building              | SUBB           | subBuilding                  |
| building\*                        | Building Name             | BNAM           | buildingName                 |
|                                   | Building Number           | BNUM           | buildingNumber               |
| poBox                             | PO Box                    | POBX           | poBox                        |
| street\*                          | Thorofare                 | THOR           | street                       |
|                                   | Dependent Thorofare       | DPTH           | subStreet                    |
| locality\*                        | Dependent Locality        | DPLO           | locality                     |
|                                   | Double Dependant Locality | DDLO           | sublocality                  |
| town                              | Post Town                 | TOWN           | town                         |
| stateRegion                       | County                    | CNTY           | stateRegion                  |
| countryCode                       | N/A                       | N/A            | countryCode                  |
| postCode                          | Postal Code               | PCOD           | postCode                     |

* Composite fields - Composite input fields offer advanced searching capabilities by searching against multiple target fields. e.g.**locality** - Searches against PAF Dependant Locality, Double Dependant Locality and PostTown.

### Data Paging Additional Records

If the number of records available from a GB Address Web Service search is greater than the specified MaxRecords value provided in the options then that additional data can be acquired through paging. To retrieve the next page of records the search should be submitted again with the offset increased to the start of the next page.

**Response XML indicating more data:**

```xml theme={null}
<req:captureResponse>
  <req:resultStatus>MULTIPLE</req:resultStatus>
  <req:recordsReturned>5</req:recordsReturned>
  <!--Paging Information:-->
  <req:moreData>false</req:moreData>
  <req:totalRecordCount>1574</req:totalRecordCount>
  <req:totalPages>16</req:totalPages>
```

**Search XML requesting more data:**

```xml theme={null}
<req:options>
  <req:addressEnvelopeFormat>A4P</req:addressEnvelopeFormat>
  <req:relatedDataItems tmp="?">
    <data:key>UBID</data:key>
  </req:relatedDataItems>
 
  <!-- Pagination Information -->
  <req:offset>5</req:offset>
  <req:maxReturn>5</req:maxReturn>
 
  <req:addressSearchLevel>PREMISE</req:addressSearchLevel>
  <req:casing>MIXED</req:casing>
</req:options>
```

## Error Information

Information on possible error codes is given here: [Error Code Information](/our-services/legacy-products/matchcode/general-information/error-codes)