Skip to content
Log inGet a demo

Matchcode 360 Integration Fundamentals

This guide explains how to access the Matchcode360 web services products, hosted on GBG’s Identity Management (IdM) platform.

Matchcode360 provides you with the ability to easily embed validation, ID-tracing and ‘location intelligence’ functionality into your own applications including:

  • Verification and capture of UK, Eire and Global addresses;
  • Capture and verification of UK residents’ names;
  • Provision of property attributes or Social Media data Insight
  • Validation of landline and mobile ‘phone numbers, email addresses and UK bank account details;
  • GBG Connexus services for tracing UK residents;

The Matchcode360 online web services provide sub-second searching of scores of industry-standard address and address-related databases from dozens of data suppliers.

This document provides a general description of the available functionality of Matchcode360 along with a definition of the corresponding interfaces used to access the different datasets and services.

Matchcode360 Web Services Information

Matchcode360 is delivered as both RESTful and SOAP web-services. XML should be used for all SOAP requests and responses.  For RESTful services, JSON or XML can be used. Matchcode360-WS can be integrated into any environment that supports the implementation of external web-services. It is not feasible however, to provide examples in all supported languages and platforms such as C#, Java, PHP, SAP, Oracle etc. and for this reason, examples below are provided in generic JSON and XML. These can be pasted directly into a tool such as Soap-UI from where they can be run directly.

Client and Server-Side use of Matchcode360

Although Matchcode360 services employ HTTPS encryption, any client-side application such as a web-browser, would at some point need to be passed the user credentials by a server-side application. If at any stage on the client app, the credentials are exposed as unencrypted, free-text, as they would be in JavaScript code for example, then this would pose a security risk.

All browsers by default don’t allow violation of Same Origin Policy (SOP) which means they do not permit cross-origin JavaScript requests. Since the clients using the browser-app are not guaranteed to be totally secure, then there is always a risk that credentials exposed within the JavaScript code can be compromised. Matchcode360 should therefore always be implemented within server-side applications which enables you to keep control of your credentials.

 

Overview of Web Service Methods

The following web service methods are used to access the IdM web service interface:

Method Name Description
authenticateUser Authenticate a user and generate a security token
executeCapture Perform name & address lookup, address verification or validate a telephone number, email or bank account. Available for SOAP and REST.
executeTrace Perform tracing, using the Connexus interface. Available for SOAP only.

 

Service Endpoint

The service endpoint for Matchcode360 is:

https://idmp.gb.co.uk

WSDL

The following WSDL can be used to generate classes within your application code that can be used to map directly to the Matchcode360 data structures:

https://idmp.gb.co.uk/idm-globalservices-ws/GlobalServices19a.wsdl

Connecting to Matchcode360

Access to Matchcode360 is provided by a login/password system. Both must be passed to the service as part of your initial connection. Please see your system administrator for login details which will have been provided by GBG's Customer Care team.

The first call is to the authenticateUser method which checks your user credentials and returns an authentication token. Once a connection has been established using the authenticateUser method and a valid authentication-token has been returned, a call to executeCapture can be made to perform an address search or phone, email or bank verification, or to executeTrace if the Connexus tracing service is to be interrogated.

The authentication token, together with the username, are then used in the request call to executeCapture or executeTrace.

The techniques of calling Matchcode360 particularly around the authentication process are slightly different for RESTful and SOAP services so each is discussed separately below.

Matchcode360 RESTful Services

Note that is you are calling executeTrace then you should use the SOAP interface. However, executeCapture may be called using SOAP or REST.

If you are using REST, then multiple executeCapture methods may be called (sequentially or in parallel) using the same authentication token. The token is persistent and the same auth-token/username combination may be re-used for subsequent calls to executeCapture without the need to re-authenticate.

However, if the token is lost or expires, then the user credentials must be authenticated again using authenticateUser. This can occur if no call is made to executeCapture within any 65-minute period. In other words, there is a 65-minute time-out of the token from the time that it was issued or last used.

Date/Timestamp

Matchcode360 uses Coordinated Universal Time (UTC) in the following date-time format

YYYY-MM-DDThh:mm:ss.cccZ

for example

2017-06-20T14:04:22.603Z

Session Termination

There is no need to close or terminate a session.

Calling Sequence

The typical sequence of calls is shown below:

authenticateUser (REST)

authenticateUser provides user/connection authentication details and when using REST, only needs to be called only once for all user connections to the service.  Once a secure connection has been established, this method does not need to be called again unless the connection is lost either because:

  • the connection has been closed due to the client application terminating, or
  • the connection has been lost due to a timeout condition (65 minutes from last call to authenticateUser or executeCapture)

The input parameters and returned data to the authenticateUser request are discussed below.  On validation of user credentials passed in to authenticateUser, for REST only, the method returns a persistent 'authentication token'.   This token is then supplied together with the username for all subsequent requests to the executeCapture method for all users/threads.

Calling authenticateUser

The call to authenticateUser comprises the endpoint, resource string and request details:

Request Type: GET
Endpoint: https://idmp.gb.co.uk
Resource: idm-core-rest-globalservices/<version>/authentication/authenticateUser
Request: username=<yourUserName>&password=<yourPassword>

where:

<version>is the current version of the Matchcode360 service.  For example, for version 21a (first version released in 2021)
<yourUserName> and <yourPassword> are the credentials given to you by GBG

Optionally, you can also pass the parameter ipAddress to authenticateUser to tie the searching to an IP address. If ipAddress is supplied to authenticateUser, then the same IP address must be provided with subsequent executeCapture requests using this authentication token.

The parameters for authenticateUser are summarised in the table below:

Type: AuthenticateUserRequest

Field Name Type Description
username String The username used to access the system including domain name (e.g. user1@mydomain.com)
password String The user's password
ipAddress String (Optional) The IPv4 Address of the requesting machine.
Note that if an ipAddress is supplied to authenticateUser, then the same ipAddress must be provided with subsequent requests using this authentication.

 

authenticateUser Example

GET host/idm-core-rest-globalservices/21a/authentication/authenticateUser?username= user1@mydomain.com&password=myPassword

authenticateUser Response

The returned data from the authenticateUser request includes:

  1. Unique authentication token and
  2. Error/success codes and
  3. Connection details

The full authenticateUser response from the REST service contains the following fields

Type: AuthenticateUserResponse

Field Name Type Description
authenticationToken String Unique authentication token to be passed into the subsequent Execute method call
authenticationTime DateTime Authentication time
fullUserName String Full user name
userGuid String The unique identifier for the user
username String User name without domain
domain String The domain name of the authenticated user
lastLogin DateTime Last login for the user
sessionExpiryTime DateTime Session expiry date and time

 

Example authenticateUser Response

 

{
    "authenticationtoken": "1c986c48-6cfd-492c-b305-04bab6eb76aa",
    "authenticationtime": "2017-06-02t09:55:30.255z",
    "fullusername": " user1@mydomain.com",
    "userguid": "359628c7-4ac3-4b33-b7fa-31fc81a8479e",
    "username": "user1",
    "domain": "mydomain.com",
    "domaintype": "organisation",
    "lastlogin": "2017-05-31t19:46:12.000z",
    "sessionexpirytime": "2017-06-02t10:56:30.255z"
}

executeCapture (REST)

executeCapture provides a method for you to lookup property data from the GBG consolidated address database using search queries.  Using the RESTful interface, following a single call to authenticateUser, multiple calls can be made to executeCapture using the same authentication token. The details of the input parameters to executeCapture are described in detail within the service-specific interface document (e.g. UK Address, Eircode, MultiDB etc.) but connection details are provided here.

The call to executeCapture comprises the endpoint, resource string and request details:

Request Type POST
Endpoint https://idmp.gb.co.uk
Resource idm-core-rest-globalservices/<version>/gbg/executeCapture
Request Header authenticationToken=<authToken>username=<yourUserName>
Request
customer reference (can be anything you wish) and
 
configuration ID(see below)  and
 
profile GUID (see below)  and one of
 
- one or more address elements (e.g. postcode, postcode + building)  or
 
- a 'free-format' address string (comma-separated 'lines' of address)  or
 
- one service-specific, unique key field such as UPRN, UDPRN, GBGURN_1


where:

<version> is the current version of the Matchcode360 service.  For example, for version 21a (first version released in 2017);
<authToken> is the authentication token returned from the last authenticateUser call;
<yourUserName> is the username used in the last authenticateUser call;

Customer reference (customerReference): This can be used for your own audit purposes to record your own information about the particular system or user submitting the request.  This field can be anything you wish.

Configuration ID (configurationId): The datasets that underpin the Matchcode360 service comprise of combinations of one or more source datasets.  For example the Matchcode360 UK Address service can search the Royal Mail PAF database alone or a combination of PAF, the Multiple Residency file and Not-Yet-Built address data together with Acorn geo-demographic data.  Depending upon your particular subscription, the Configuration ID can be used to restrict or expand the data sets searched by the service for different users or groups of users.

The Matchcode360 Utilities Register service could have two configurations created, for example, so that configurationId=1 would search the 'Utilities Standard' database and configurationId=2 would search the 'Utilities Premium' data.

This can be configured by any user with Adminstrator access (from the login homepage)

Administration > Product > Setting > View/Edit > Add configuration

Profile GUID (profileGuid): Each of the Matchcode360 web services (UK Address, Global Address, Eircode, Utilities Register etc.) is identified by a separate Profile GUID.  Your subscription will licence you for one or more services and you should specify the service you are calling using the Profile GUID.

In addition to the above request fields, a number of other fields are required including, the particular item you wish to search or validate such as postcode, free-format address, email address or 'phone number. Other options can be included to configure the search and the returned response, including the specification of particular elements of address-related data to be returned, address formatting, paging and casing directives.

The full set of parameter options for executeCapture are detailed in the documentation for each particular service (UK Address, Global Address, Eircode, Utilities Register etc.) However, an example of a simple executeCapture request to the Matchcode360 Utilities Register Premium service is given below:


POST https://idmp.gb.co.uk/idm-core-rest-globalservices/21a/gbg/executeCapture HTTP/1.1
Accept-Encoding: gzip,deflate
username: user1@myDomain.com
authenticationToken: 3CA978A5-DBEE-418B-A6BB-3401D8D1FFC5
Content-Type: application/json
Content-Length: 478
Host: idmp.gb.co.uk
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

{
    "customerReference": "Test",
    "profileGuid": "942A500C-F57F-4C7B-9C1D-0F8246CA3890",
    "configurationId": "2",
    "requestData":   {
        "address": {
            "building": "",
            "postCode": "CH4 9GB",
            "freeFormatAddress":""
            },
        "options":   {
            "addressEnvelopeFormat": "A3TCP",
            "offset": "0",
            "maxReturn": "50",
            "addressSearchLevel": "PREMISE",
            "casing": "MIXED"
        }
    }
}

Matchcode360 SOAP Services

Note that if you are calling executeTrace then you should use the SOAP interface.  executeCapture may be called through SOAP or REST.

If you are using SOAP, then a new authentication token must be used for each search or validation request.  Additionally, if a valid token is lost or expires, then the user credentials must be authenticated again using authenticateUser. This can occur if no call is made to executeCapture within any 65-minute period.  In other words, there is a 65-minute time-out of the token from the time that it was issued or last used.

Date/Timestamp

Matchcode360 uses Coordinated Universal Time (UTC) in the following date-time format

YYYY-MM-DDThh:mm:ss.cccZ

for example

2017-06-20T14:04:22.603Z

Session Termination

There is no need to close or terminate a session.

Calling Sequence

The typical sequence of calls for the Matchcode360 SOAP services is shown below:

Matchcode360 authenticateUser (SOAP)

authenticateUser provides user/connection authentication details and should be called only once for each new user or thread connection to the service.  Additionally the method will need to be called again if the connection is lost either:

  • because the connection has been closed due to the client application terminating, or
  • because the connection has been lost due to a timeout condition (65 minutes from last call to authenticateUser or executeCapture)

The input parameters and returned data to the authenticateUser request are discussed below.  The general operation of this method is that it is called with a username and password supplied by GBG.  On validation of these credentials, the method for SOAP only, returns a single-use 'authentication token'.   This token is then supplied together with the username for the first addressing request using executeCapture or executeTrace methods.

Unlike the REST services, where a single token can be used multiple times simultaneously by many threads or users, when using SOAP, an authentication token is valid for only one search request for one user/thread. However, this does not mean that you need to call authenticateUser to obtain a fresh auth-token as the response from the executeCapture call contains a new valid token for the subsequent address search.

In a multi-user scenario, you will generally want run your requests in parallel rather than queue them up sequentially.  One way of doing this is to hold a pool of pre-authenticated, valid auth-tokens by making a number of calls to authenticateUser ahead of any executeCapture requests. The tokens returned with each executeCapture response should be returned to the pool.  You should estimate your expected average and peak loads and scale the size of the pool accordingly taking into account the average response times.  These will vary depending upon the service you are calling (whether UK Address or email validation for example) and the type of search you are performing: A postcode search on the UK Address service will typically complete in 300-500ms for example.

You may wish to develop a process to monitor the token-pool and decide whether you want to make additional calls to authenticateUser if the pool runs dry or to queue up your requests which may have an performance impact on your overall system.   

One way to overcome this problem is to implement a simple demand manager that monitors the user-load and scales the size of the free-token pool accordingly when the number of free tokens reaches an upper or lower threshold.

Calling authenticateUser

The SOAP endpoint for authenticateUser is as follows:

Endpoint: https://idmp.gb.co.uk/idm-globalservices-ws/services/<version>

where:

<version>is the current version of the Matchcode360 service.  For example, for version 21a (first version released in 2021)

User credentials are passed to authenticateUser within the body of the request.

Optionally, you can also pass the parameter ipAddress to authenticateUser to tie the searching to an IP address. If ipAddress is supplied to authenticateUser, then the same IP address must be provided with subsequent executeCapture requests using this authentication token.

The parameters for authenticateUser are summarised in the table below:

Type: AuthenticateUserRequest

Field Name Type Description
username String The username used to access the system including domain name (e.g. user1@mydomain.com)
password String The user's password
ipAddress String (Optional) The IPv4 Address of the requesting machine.
Note that if an ipAddress is supplied to authenticateUser, then the same ipAddress must be provided with subsequent requests using this authentication.

authenticateUser Example (SOAP)

<soapenv:Envelope xmlns:soapenv=" http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:mes=" http://gbworld.gb.co.uk/idm-globalservices/messages/21a/">
    <soapenv:Header/>
    <soapenv:Body>
        <mes:AuthenticateUserRequest>
            <mes:username>user1@myDomain.com</mes:username>
            <mes:password>myPassword</mes:password>
            <mes:ipAddress>127.0.0.1</mes:ipAddress>
        </mes:AuthenticateUserRequest>
    </soapenv:Body>
</soapenv:Envelope>
authenticateUser Response (SOAP)

The returned data from the authenticateUser request includes:

  1. Unique authentication token and
  2. Error/success codes and
  3. Connection details


The full authenticateUser response from the SOAP service contains the following fields

Type: AuthenticateUserResponse

Field Name Type Description
authenticationToken String Unique authentication token to be passed into the subsequent Execute method call
authenticationTime DateTime Authentication time
fullUserName String Full user name
userGuid String The unique identifier for the user
userName String User name without domain
domain String The domain name of the authenticated user
lastLogin DateTime Last login for the user
passwordExpiryDate DateTime Password expiry date and time
sessionExpiryTime DateTime Session expiry date and time

 

 Example response


<SOAP-ENV:Envelope xmlns:SOAP-ENV=" http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <mes:AuthenticateUserResponse xmlns:mes=" http://gbworld.gb.co.uk/idm-globalservices/messages/21a/"
            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:authenticationToken>613DDE01-BAB0-4331-BB6F-7D71C4FA03BE</mes:authenticationToken>
            <mes:authenticationTime>2012-12-17T19:09:45.904Z</mes:authenticationTime>
            <mes:displayName xsi:nil="true" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"/>
            <mes:fullUsername>user1@myDomain.com</mes:fullUsername>
            <mes:userGuid>A44F26EF-6893-4C97-8DA4-9EC143A7DA2F</mes:userGuid>
            <mes:username>user1</mes:username>
            <mes:domain>myDomain.com</mes:domain>
            <mes:domainType>ORGANISATION</mes:domainType>
            <mes:lastLogin>2012-12-13T11:33:15.000Z</mes:lastLogin>
            <mes:passwordExpiryDate xsi:nil="true" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"/>
            <mes:sessionExpiryTime>2012-12-17T19:39:45.905Z</mes:sessionExpiryTime>
        </mes:AuthenticateUserResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example error response


<SOAP-ENV:Envelope xmlns:SOAP-ENV=" http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <SOAP-ENV:Fault>
            <faultcode>SOAP-ENV:Client</faultcode>
            <faultstring xml:lang="en">Invalid authentication details supplied.</faultstring>
            <detail>
                <mes:BusinessException xmlns:mes=" http://gbworld.gb.co.uk/types/faults/">
                    <transactionId xmlns=" http://gbworld.gb.co.uk/types/faults/">46EAE6A3-A055-430A-84ED-A7BAB992B1DC</transactionId>
                    <detail xmlns=" http://gbworld.gb.co.uk/types/faults/">
                        <errorCode>BE010009</errorCode>
                        <errorMessage/>
                    </detail>
                </mes:BusinessException>
            </detail>
        </SOAP-ENV:Fault>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

executeCapture (SOAP)

executeCapture provides a method for you to lookup property data from the GBG consolidated address database using search queries.  Using the SOAP interface, a fresh authentication token is required for each executeCapture call.  This is obtained from a call to authenticateUser or returned from a previous call to executeCapture as described above.

The details of the input parameters to executeCapture are described in detail within the service-specific interface document (e.g. UK Address, Eircode, MultiDB etc.) but connection details are provided here.

The SOAP endpoint for executeCapture is as follows:

Endpoint: https://idmp.gb.co.uk/idm-globalservices-ws/services/<version>

where:

<version>is the current version of the Matchcode360 service.  For example, for version 21a (first version released in 2021)

There are a number of mandatory fields that need to be passed to executeCapture including a valid authentication token and username and the particular data field(s) you are searching or validating such as postcode, free-format address, email address or 'phone number.  In addition the following key fields are used with each call: 

Customer reference (customerReference): This can be used for your own audit purposes to record your own information about the particular system or user submitting the request.  This field can be anything you wish.

Configuration ID (configurationId): The datasets that underpin the Matchcode360 service comprise of combinations of one or more source datasets.  For example the Matchcode360 UK Address service can search the Royal Mail PAF database alone or a combination of PAF, the Multiple Residency file and Not-Yet-Built address data together with Acorn geo-demographic data.  Depending upon your particular subscription, the Configuration ID can be used to restrict or expand the data sets searched by the service for different users or groups of users.

The Matchcode360 Utilities Register service could have two configurations created, for example, so that configurationId=1 would search the 'Utilities Standard' database and configurationId=2 would search the 'Utilities Premium' data.

This can be configured by any user with Adminstrator access (from the login homepage)

Administration > Product > Setting > View/Edit > Add configuration

Profile GUID (profileGuid): Each of the Matchcode360 web services (UK Address, Global Address, Eircode, Utilities Register etc.) is identified by a separate Profile GUID.  Your subscription will licence you for one or more services and you should specify the service you are calling using the Profile GUID.

In addition to the above request fields, a number of other options can be included to configure the search and the returned response, including the specification of particular elements of address-related data to be returned, address formatting, paging and casing directives.

The full set of parameter options for executeCapture are detailed in the documentation for each particular service (UK Address, Global Address, Eircode, Utilities Register etc.) However, an example of a simple executeCapture request to the Matchcode360 Utilities Register Premium service is given below:

The parameters for executeCapture are detailed in the documentation for each particular service (e.g. UK Address, Global Address, Utilities Register etc.) However, an example of a simple executeCapture request to the Matchcode360 Utilities Register Premium service is given below:


<soapenv:envelope xmlns:soapenv=" http://schemas.xmlsoap.org/soap/envelope/"
                    xmlns:a=" http://gbworld.gb.co.uk/idm-globalservices/messages/21a/"
                    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>user1@myDomain.com</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>

Get started for free today

  • No credit card required
  • Cancel any time
  • 24/5 support
Get started