Sending a request to the Phonematch web service
To access the data provided by the Phonematch web service, you must send a request via a URL containing:
- Your user authentication details (Key)
- A set of parameter values on which you wish to conduct a Phonematch search
On setting up your account, our web service support team will supply you with a consumer key and a consumer secret; these form your authentication details.
A consumer key is your unique identifier, and identifies you to the Phonematch web service; the consumer secret confirms that you own the consumer key and therefore verifies that you have permission to use the key. This dual validation process, which utilises OAuth protocols, makes the authentication process extremely secure.
To conduct a successful search the request URL (search object) must contain the following parameter values as a minimum:
- Forename (or initial), surname, address line 1, postcode, landlineService, mobileService
Request parameters, their data types and permissible formats, are highlighted in the table below, with supporting notes:
Authentication parameters
| Parameter | Data Type | Possible Formats | Notes |
|---|---|---|---|
| consumer key | Alphanumeric | a-z, A-Z, 0-9 40 character string |
User must be authenticated for every search |
| consumer secret | Alphanumeric | a-z, A-Z, 0-9 40 character string |
User must be authenticated for every search |
Search object parameters
| Parameter | Data Type | Possible Formats | Notes |
|---|---|---|---|
| landlineService | Alpha | 'N','A','P' | N = Not searched, A = Phonematch Advanced, P = Phonematch Premium |
| mobileService | Alpha | 'N','A','P' | N = Not searched, A = Phonematch Advanced, P = Phonematch Premium |
| forename | Alpha | a-z, A-Z, - 70 characters max |
Required value. An initial is the minimum requirement. |
| middleName | Alpha | a-z, A-Z, - 32 characters max |
Optional value; middle name can help improve the likelihood of a response being related to the search. |
| surname | Alpha | a-z, A-Z, -
35 characters max |
Required value |
| address1 | Alphanumeric | a-z, A-Z, 0-9, 64 characters max |
When entering an address, postcode must be provided, and is the
minimum value which can be entered. An address (full or partial) must be provided with every request. |
| address2 | Alphanumeric | a-z, A-Z, 0-9, -
64 characters max |
As Above |
| address3 | Alphanumeric | a-z, A-Z, 0-9, -
64 characters max |
As Above |
| address4 | Alphanumeric | a-z, A-Z, 0-9, -
64 characters max |
As Above |
| address5 | Alphanumeric | a-z, A-Z, 0-9, -
64 characters max |
As above |
| postcode | Alphanumeric | a-z, A-Z, 0-9, -
7 characters min 8 characters max |
Postcode is the minimum value required when providing an address.
An address (full or partial) must be provided with every request. |
| requestReference | Alphanumeric | a-z, A-Z, 0-9, - , _
32 characters max |
The requestReference parameter allows you to provide a unique reference for each search you conduct. |
| ignoreNumbers | Number | 0-9, , | A comma separated list of telephone numbers that should not be returned. |