Global Telephone Validation Integration Guide
This guide explains how to access GBGroup's Global Telephone Validation web service product using their Identity Management Platform (IdM), available via SOAP web services.
The fundamentals of integrating with the service are described here: Integration Fundamentals
Matchcode Global Telephone Validation Service
The global telephone validation service first checks that the provided telephone number conforms to the valid syntax required for a telephone number for the country specified. For all mobile and UK Landline numbers, further real-time checks are then carried out to assess the validity of the number and, for mobiles, such details as whether the number is roaming and the current location.
There are two services available - the 'Full' service carries out all checks as described above. There is also a 'Rapid' service, here results from previous lookups of the Full service are cached for 3 days and the Rapid service looks up these cached results. The advantage of the Rapid service is one of speed and an increased amount of numbers than can be looked up in one webservice call. This has to be offset against the fact that the results are not 'live' and there is a small chance of them having changed since being cached. Also, the number looked up may not be in the cache at all. In addition there is a 'Telephone_Fast' option whereby the user can specify the number of days to look back in the cache.
The Matchcode Validation Service products are available via the Identity Management ExecuteCapture web service method.
Global Telephone Validation - Input Criteria
Method: ExecuteCapture
The ExecuteCapture method is used to access the Global Telephone Validation product and services by specifying the corresponding profile.
Input Details
Type: ExecuteCaptureRequest
| Field Name | Type | Description |
|---|---|---|
| securityHeader | SecurityHeader | The username used to access the system including domain name (e.g. user1@domainname.com) |
| profileRequest | ProfileRequestCapture | Details of the request |
In the profileRequest element, the profileGuid should be specified as:
| Profile | GUID |
| Global Telephone (Full) | 454F13CA-8C71-40D6-9FEF-A88D821C99E4 |
| Global Telephone (Rapid) | 315559EB-94DD-49B8-8277-FEEB42CD6820 |
Telephone Validation Criteria
The input telephone information should be entered into the IdMDataCaptureTelephone data structure:
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → IdMDataCaptureTelephone
Type: IdMDataCaptureTelephone
| Field Name | Type | Description |
|---|---|---|
| number | String | Telephone Number (International format including dialing code e.g. +44) |
| type | EnumTelephone | Specifies the type of telephone provided
MOBILE, LANDLINE, UNKNOWN |
Maximum Telephone Numbers
For the Full service a maximum of 10 numbers can be entered into any one executeCapture request, for the rapid service a maximum of 100 numbers can be entered.
Country Code
The 3 letter ISO code for the country can be entered into the countryCode element of the address structure. Note: The country code is used to format numbers that are entered in the 'local' format for the country specified (e.g. 012446573333 for UK). If more than one number is validated and they are from different countries then they should be entered in full international format (e.g. +441244657333).
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → IdMDataSearchAddress → countryCode
Additional Features
Additional information can be requested to be returned by providing the key value pairs specified below to the ProfileRequestCaptureData → additionalData property.
The TELEPHONE_FAST option allows the user specify how many days to look back in the cached results. A value of 0 will mean the lookup is always live, other values will look back in the cache for the number of days set.
The advantage of this is one of speed and an increased pool of numbers than can be looked up in one webservice call. This has to be offset against the fact that the results are not 'live' and there is therefore an increased chance of the status of the number having changed since being cached.
In summary, increasing cache days is likely to improve response times but will reduce the recency of the result.
Please note the default setting of the telephone validation service is to reference one day of Cache results, i.e. TELEPHONE_FAST=1
This information should be entered into a IdmDataArrayAdditionalData data structure:
ExecuteCapture → ProfileRequestCapture → ProfileRequestCaptureData → additionalData
Type: IdmDataArrayAdditionalData
Below is a list of addition data fields:
| Key Mnemonic | Key Value | Description |
|---|---|---|
| TELEPHONE_FAST | Integer | Number of days cache to reference |
Telephone Input XML
The following XML sample demonstrates a request data object containing both an Address and two telephone numbers for validation. Where possible the telephone numbers should be provided with the international dialling code (e.g. +44 for UK) or the country code can be provided in the address object (e.g. GBR for UK). Each telephone number entered allows you to specify a type of either MOBILE, LANDLINE or UNKNOWN. The UNKNOWN type will attempt to work out the correct number type based upon the input format.
<!-- request input data - telephone -->
<req:requestdata>
<req:address>
<data:countrycode>gbr</data:countrycode>
</req:address>
<!-- telephone input data -->
<req:telephone>
<data:number>+441244657231</data:number>
<data:type>landline</data:type>
</req:telephone>
<req:telephone>
<data:number>07123456789</data:number>
<data:type>mobile</data:type>
</req:telephone>
<!-- request options -->
<req:options>
<req:offset>0</req:offset>
<req:maxreturn>10</req:maxreturn>
</req:options>
<req:additionaldata tmp="?">
<data:item>
<data:key>payg</data:key>
<data:value>yes</data:value>
</data:item>
<data:item>
<data:key>telephone_fast</data:key>
<data:value>5</data:value>
</data:item>
</req:additionaldata tmp="?">
</req:requestdata>{
"requestdata": {
"address": { "countrycode": "gbr" },
"telephone": [
{
"number": "+441244657231",
"type": "landline"
},
{
"number": "07123456789",
"type": "mobile"
}
],
"options": {
"offset": "0",
"maxreturn": "10"
},
"additionaldata": {
"data:item": [
{
"data:key": "payg",
"data:value": "no"
},
{
"data:key": "telephone_fast",
"data:value": "5"
}
]
}
}
}Telephone Output Format
The results of the GB Telephone Web Service search are returned in a ProfileResponseDetails structure with a ProfileResponseDetails → responseType of 'VALIDATE'.
The ProfileResponseDetails structure contains a single ValidateResponse data structure which holds an array of ValidateResponseData records containing the returned validation data per input number.
ExecuteCaptureResponse → ProfileResponse [0] → ProfileResponseDetails [0] → ValidateResponse → ValidateResponseData
The returned ValidateResponseData data structure is detailed below:
Type: ValidateResponseData
| Field Name | Type | Description |
|---|---|---|
| input | String | The input telephone number |
| status | Enumeration | SUCCESS if the validation has taken place, FAILURE otherwise |
| validityFlag | Enumeration | Overall validation result of the number (VALID, INVALID, UNKNOWN, UNSUPPORTED) |
| validationCodes | IdmDataArrayAdditionalData | Array of key value pairs containing the validation response codes for the number |
Sample Output XML
The following output XML demonstrates the ProfileResponse for the telephone component. The component name is Global Telephone and the response type is VALIDATE.
The validation results for each telephone number will be returned in the same order as input. The array of ValidateResponse data structures contain the individual response details. The primary response value is validityFlag which dictates whether or not the number has been deemed to be valid or not. In addition a series of key value pair response codes are returned for each number, which contain data supplier specific summaries of the input number.
<!-- telephone component response -->
<req:profileresponsedetails>
<req:transactionguid>32fba7e0-7ae5-43b7-93dc-357b593b4d87</req:transactionguid>
<req:componentname>global telephone</req:componentname>
<req:componentstatus>success</req:componentstatus>
<req:componentaction>telephoneauto</req:componentaction>
<req:responsetype>validate</req:responsetype>
<req:notes>[]</req:notes>
<!-- billing invoice -->
<req:invoice>
<req:invoicelist>
<req:invoiceguid>e4c1e94c-f39d-405b-8842-f1f6b1b5763f</req:invoiceguid>
<req:billinginformationguid>a8c19479-a562-4604-b5e2-97a93aea45d6</req:billinginformationguid>
<req:billingpoints>2</req:billingpoints>
<req:datasetinvoices>
<req:datasetcode>telephone</req:datasetcode>
<req:billingpoints>2</req:billingpoints>
<req:recordsreturned>2</req:recordsreturned>
<req:datalicenceguid>a8c19479-a562-4604-b5e2-97a93aea45d6</req:datalicenceguid>
</req:datasetinvoices>
</req:invoicelist>
</req:invoice>
<!-- response data -->
<req:validateresponse>
<req:resultstatus>verify</req:resultstatus>
<req:recordsreturned>2</req:recordsreturned>
<req:responsecount>2</req:responsecount>
<!-- response per input number -->
<req:response>
<req:input>+441244657321</req:input>
<req:status>success</req:status>
<req:validityflag>valid</req:validityflag>
<req:validationcodes>
<data:item>
<data:key>resultcode</data:key>
<data:value>100</data:value>
</data:item>
<data:item>
<data:key>resultcodedescription</data:key>
<data:value>live number</data:value>
</data:item>
<data:item>
<data:key>numbertype</data:key>
<data:value>landline</data:value>
</data:item>
<data:item>
<data:key>inputnumber</data:key>
<data:value>+441244657321</data:value>
</data:item>
<data:item>
<data:key>outputnumber</data:key>
<data:value>01244657321</data:value>
</data:item>
<data:item>
<data:key>originalcountryiso3code</data:key>
<data:value>gbr</data:value>
</data:item>
<data:item>
<data:key>originalcountryname</data:key>
<data:value>united kingdom</data:value>
</data:item>
<data:item>
<data:key>originalcountryprefix</data:key>
<data:value>44</data:value>
</data:item>
<data:item>
<data:key>ofcomallocated</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>ofcomprovider</data:key>
<data:value>bt</data:value>
</data:item>
</req:validationcodes>
</req:response>
<req:response>
<req:input>07123456789</req:input>
<req:status>success</req:status>
<req:validityflag>valid</req:validityflag>
<req:validationcodes>
<data:item>
<data:key>numbertype</data:key>
<data:value>mobile</data:value>
</data:item>
<data:item>
<data:key>inputnumber</data:key>
<data:value>07123456789</data:value>
</data:item>
<data:item>
<data:key>ofcomallocated</data:key>
<data:value>true</data:value>
</data:item>
<data:item>
<data:key>ofcomprovider</data:key>
<data:value>orange</data:value>
</data:item>
<data:item>
<data:key>ofcomnotes</data:key>
<data:value>mobile services</data:value>
</data:item>
<data:item>
<data:key>resultcode</data:key>
<data:value>100</data:value>
</data:item>
<data:item>
<data:key>resultcodedescription</data:key>
<data:value>live number</data:value>
</data:item>
<data:item>
<data:key>outputnumber</data:key>
<data:value>447123456789</data:value>
</data:item>
<data:item>
<data:key>status</data:key>
<data:value>delivrd</data:value>
</data:item>
<data:item>
<data:key>imsi</data:key>
<data:value>234330188089882</data:value>
</data:item>
<data:item>
<data:key>mcc</data:key>
<data:value>234</data:value>
</data:item>
<data:item>
<data:key>mnc</data:key>
<data:value>33</data:value>
</data:item>
<data:item>
<data:key>originalcountryiso3code</data:key>
<data:value>gbr</data:value>
</data:item>
<data:item>
<data:key>originalcountryname</data:key>
<data:value>united kingdom</data:value>
</data:item>
<data:item>
<data:key>originalcountryprefix</data:key>
<data:value>44</data:value>
</data:item>
<data:item>
<data:key>originalnetworkname</data:key>
<data:value>orange (everything everywhere limited)</data:value>
</data:item>
<data:item>
<data:key>originalnetworkprefix</data:key>
<data:value>79700</data:value>
</data:item>
<data:item>
<data:key>isroaming</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>roamingcountryname</data:key>
<data:value>united kingdom</data:value>
</data:item>
<data:item>
<data:key>roamingnetworkname</data:key>
<data:value>t-mobile uk (everything everywhere limited)</data:value>
</data:item>
<data:item>
<data:key>roamingcountryprefix</data:key>
<data:value>44</data:value>
</data:item>
<data:item>
<data:key>roamingnetworkprefix</data:key>
<data:value>79537</data:value>
</data:item>
<data:item>
<data:key>roamingcountryiso3code</data:key>
<data:value>gbr</data:value>
</data:item>
<data:item>
<data:key>roamingcountrymcc</data:key>
<data:value>234</data:value>
</data:item>
<data:item>
<data:key>isported</data:key>
<data:value>false</data:value>
</data:item>
<data:item>
<data:key>portedcountryname</data:key>
<data:value>united kingdom</data:value>
</data:item>
<data:item>
<data:key>portednetworkname</data:key>
<data:value>orange (everything everywhere limited)</data:value>
</data:item>
<data:item>
<data:key>portedcountryprefix</data:key>
<data:value>44</data:value>
</data:item>
<data:item>
<data:key>portednetworkprefix</data:key>
<data:value>74091</data:value>
</data:item>
<data:item>
<data:key>portedcountryiso3code</data:key>
<data:value>gbr</data:value>
</data:item>
<data:item>
<data:key>portedcountrymcc</data:key>
<data:value>234</data:value>
</data:item>
<data:item>
<data:key>validationdate</data:key>
<data:value>2015-05-18</data:value>
</data:item>
<data:item>
<data:key>payg</data:key>
<data:value>contract</data:value>
</data:item>
</req:validationcodes>
</req:response>
</req:validateresponse>
</req:profileresponsedetails>{
"profileresponsedetails": {
"transactionguid": "32fba7e0-7ae5-43b7-93dc-357b593b4d87",
"componentname": "global telephone",
"componentstatus": "success",
"componentaction": "telephoneauto",
"responsetype": "validate",
"notes": "[]",
"invoice": {
"invoicelist": {
"invoiceguid": "e4c1e94c-f39d-405b-8842-f1f6b1b5763f",
"billinginformationguid": "a8c19479-a562-4604-b5e2-97a93aea45d6",
"billingpoints": "2",
"datasetinvoices": {
"datasetcode": "telephone",
"billingpoints": "2",
"recordsreturned": "2",
"datalicenceguid": "a8c19479-a562-4604-b5e2-97a93aea45d6"
}
}
},
"validateresponse": {
"resultstatus": "verify",
"recordsreturned": "2",
"responsecount": "2",
"response": [
{
"input": "+441244657321",
"status": "success",
"validityflag": "valid",
"validationcodes": {
"item": [
{
"key": "resultcode",
"value": "100"
},
{
"key": "resultcodedescription",
"value": "live number"
},
{
"key": "numbertype",
"value": "landline"
},
{
"key": "inputnumber",
"value": "+441244657321"
},
{
"key": "outputnumber",
"value": "01244657321"
},
{
"key": "originalcountryiso3code",
"value": "gbr"
},
{
"key": "originalcountryname",
"value": "united kingdom"
},
{
"key": "originalcountryprefix",
"value": "44"
},
{
"key": "ofcomallocated",
"value": "true"
},
{
"key": "ofcomprovider",
"value": "bt"
}
]
}
},
{
"input": "07123456789",
"status": "success",
"validityflag": "valid",
"validationcodes": {
"item": [
{
"key": "numbertype",
"value": "mobile"
},
{
"key": "inputnumber",
"value": "07123456789"
},
{
"key": "ofcomallocated",
"value": "true"
},
{
"key": "ofcomprovider",
"value": "orange"
},
{
"key": "ofcomnotes",
"value": "mobile services"
},
{
"key": "resultcode",
"value": "100"
},
{
"key": "resultcodedescription",
"value": "live number"
},
{
"key": "outputnumber",
"value": "447123456789"
},
{
"key": "status",
"value": "delivrd"
},
{
"key": "imsi",
"value": "234330188089882"
},
{
"key": "mcc",
"value": "234"
},
{
"key": "mnc",
"value": "33"
},
{
"key": "originalcountryiso3code",
"value": "gbr"
},
{
"key": "originalcountryname",
"value": "united kingdom"
},
{
"key": "originalcountryprefix",
"value": "44"
},
{
"key": "originalnetworkname",
"value": "orange (everything everywhere limited)"
},
{
"key": "originalnetworkprefix",
"value": "79700"
},
{
"key": "isroaming",
"value": "false"
},
{
"key": "roamingcountryname",
"value": "united kingdom"
},
{
"key": "roamingnetworkname",
"value": "t-mobile uk (everything everywhere limited)"
},
{
"key": "roamingcountryprefix",
"value": "44"
},
{
"key": "roamingnetworkprefix",
"value": "79537"
},
{
"key": "roamingcountryiso3code",
"value": "gbr"
},
{
"key": "roamingcountrymcc",
"value": "234"
},
{
"key": "isported",
"value": "false"
},
{
"key": "portedcountryname",
"value": "united kingdom"
},
{
"key": "portednetworkname",
"value": "orange (everything everywhere limited)"
},
{
"key": "portedcountryprefix",
"value": "44"
},
{
"key": "portednetworkprefix",
"value": "74091"
},
{
"key": "portedcountryiso3code",
"value": "gbr"
},
{
"key": "portedcountrymcc",
"value": "234"
},
{
"key": "validationdate",
"value": "2015-05-18"
},
{
"key": "payg",
"value": "contract"
}
]
}
}
]
}
}
}Detailed Telephone Responses
| Name | Description |
|---|---|
| NumberType | Number type supplied b within the request(LANDLINE / MOBILE / UNKOWN) |
| InputNumber | Number as supplied within the request |
| ResultCode | GBG's Result code as an interpretation of the Syntax check or results from supplier. (see below) |
| ResultCodeDescription | Meaning of the result code |
| OutputNumber | GBG's reformatted number being used to perform a live check |
| Status | The status for the number based as an interpretation from the live HLR lookup |
| IMSI | International mobile subscriber identity |
| MCC | Mobile country code |
| MNC | Mobile network code |
| OriginalCountryName | Original Country name of Mobile number |
| OriginalNetworkName | Original Network name |
| OriginalCountryPrefix | Original mobile number country dialling prefix |
| OriginalNetworkPrefix | The Network code of the mobile number Original Network |
| OriginalCountryISO3Code | ISO 3 country code of Original country for Mobile number |
| IsRoaming | Indication whether the phone is roaming in other country |
| RoamingCountryName | The roaming Country name of Mobile number |
| RoamingNetworkName | Original Network name |
| RoamingCountryPrefix | Original mobile number country dialling prefix |
| RoamingNetworkPrefix | The Network code of the mobile number Original Network |
| RoamingCountryISO3Code | ISO 3 country code of Original country for Mobile number |
| RoamingCountryMCC | Mobile country code of the country where Mobile number is indicated as roaming |
| IsPorted | Indication whether the mobile number was ported to a different network |
| PortedCountryName | The Country name of Mobile number is ported to. |
| PortedNetworkName | The ported Network name |
| PortedCountryPrefix | Mobile number ported country dialling prefix. |
| PortedNetworkPrefix | The Network code of the mobile number ported Network |
| OfcomAllocated | true or false - number appears in UK Ofcom number allocation tables (for UK numbers only) |
| OfcomProvider | If OfcomAllocated is true this shows the provider (e.g. BT or Virgin) that the number was originally allocated to (Note number may have since been ported - for UK numbers only) |
| OfcomNotes | Optional set of notes which Ofcom may provide about the number (for UK numbers only) |
| ValidationDate | Date on which the data was checked |
Telephone Result Codes
| Code | Description | Details |
|---|---|---|
| 1 | Unknown Subscriber | Indicates that the number is a Canadian landline number. Although valid, in most cases it is unable to process SMS traffic and voice mail can be associated with such numbers. |
| 100 | Live Number | Number is live on telecoms provider network |
| 110 | Number allocated to BT, likely to be live or unobtainable | For BT exchanges, likely to be live or unobtainable (see 610) |
| 120 | Live number. But phone is switched off | Live mobile but detailed info not available due to mobile being switched off |
| 150 | Live number. Assumed mobile | Where an 'unknown' number could not be determined to be landline or mobile, the number is validated as a mobile and found to be live |
| 200 | Live Call Barred | At the time of validation the number was 'live' but an attempt to call it would result in a 'call barred' message. |
| 300 | Dead numdber | Dead / unobtainable / unconnectable / rejected number. |
| 310 | Number allocated to non-BT provider, likely to be dead | For non-BT exchanges, likley to be dead. (see 610) |
| 400 | Failed syntax check | Pre-processing of the numbers is made to check or a valid number format. E.g. numbers must be between 8 and 11 digits, must not contain non-numeric characters (although brackets, spaces and hyphens are stripped out). Also for UK numbers a check is made against a list of Ofcom registered codes to ensure that the number has a correct area code and has been allocated. Also attempts to landline verify a mobile number or vice versa. |
| 500 | Number Changed | Live number but if you phoned this number, a recording will give you a new number to call. |
| 600 | Retry 'Normal' | Unverified - Status unknown. Contact cannot be made with the number (e.g. no response at all) so no further information can be given regarding whether the number is good or not i.e. 'status unknown', classified as a retry because trying again later may yield a positive result |
| 610 | Retry Unobtainable | The number would give a 'number unobtainable' message. Reasons for this are many (customer has not paid the bill, or incoming calls not accepted). The number is registered at the exchange but unobtainable at the time of validation, which is subtly different from a dead number (i.e. not available at all). Classified as a retry as it's possible that this number may become available after some time. Now split into 310 (non-BT Exchange) and 110 (BT Exchange). |
| 620 | Retry Number Out Of Order | The number is registered but could not be reached at the time of validating due to faults with the equipment at the other end of the line. This is classified as a retry as the fault may be temporary. |
| 630 | Retry Network Out Of Order | The number is registered but could not be reached at the time of validating due to faults with the telephone network. This is classified as a retry as the fault may be temporary. |
| 640 | Retry Network Congestion | The number could not be validated because the telephone network reported congestion at the time of validation. This is classified as a retry as network congestion tends to be temporary. |
| 650 | Retry Temporary Equipment Failure | The number is registered however there was a failure with the call due to a temporary fault of equipment at the network. |
| 660 | Retry. Mobile Phone temporarily unavailable | The mobile validation service is temporarily unavailable. This is classified as a retry as the fault may be temporary. |
| 700 | Valid number format but live check not supported: Country = country name | Our live Landline Verification service only operates on UK landline numbers. If the number entered was a non UK number but conformed to the correct syntax for a landline for that country then this result code is returned. |
| 710 | Not Live Mobile, Indicated Landline | Some countries (e.g. USA and Canada) do not allocate specific number ranges to mobile phones. If the number submitted is defined as "MOBILE" and it is discovered to be a landline this result will be returned. Note: the number may be live - it is just not a mobile so won't have had a full live validation performed. |
| 720 | Indicated Landline, Valid format | Some countries (e.g. USA and Canada) do not allocate specific number ranges to mobile phones. If the number submitted is defined as "UNKNOWN" and it is discovered to be a landline this result will be returned. Note: the number may be live - it is just not a mobile so won't have had a full live validation performed. |
| 730 | HLR look-up unavailable for this network | Full live validation is not possible on some Mobile Networks (e.g. older CDMA networks). If this is the case, as much information as possible will be returned but a a full live validation cannot be performed . |
| 740 | Mobile Detected | Number was submitted as landline, but mobile was detected |
| 750 | Landline Detected | Number was submitted as mobile, but landline was detected |
| 800 | Number not found in cache for Rapid service | The number was not in the cache when using the Global Telephone Rapid service |
| 900 | New status information received from Mobile service | New status information has been received from mobile service. This should be used in conjuncton with the status field to determine the result. |
Error Information
Information on possible error codes is given here: Error Code Information