Matchcode360 Integration Fundamentals
Please note that this is a legacy product in retirement.
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:
Example authenticateUser Response
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
Example response:
Example error response
- 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;
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.ukWSDL
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.wsdlConnecting 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.603ZSession 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)
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=myPasswordauthenticateUser Response
The returned data from the authenticateUser request includes:- Unique authentication token and
- Error/success codes and
- Connection details
| 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 |
| astLogin | DateTime | Last login for the user |
| sessionExpiryTime | DateTime | Session expiry date and time |
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 |
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.603ZSession 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)
authenticateUser Response (SOAP)
The returned data from the authenticateUser request includes:- Unique authentication token and
- Error/success codes and
- Connection details
| 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 |
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