Sending a request to the People Search web service

To access the data provided by the People Search web service, you must send a request via a URL containing:

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 People Search 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:

Please note, however that a maximum number of 200 results will be provided per request. The request may need to be refined to ensure the number of results is under 200.

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
name1 String a-z, A-Z, - 70 characters max Full name of the first person with each name element separated by a space, e.g. John Alan Smith. Should the forename, middle name or surname contain a spaces, the separate forename, middle name and surname fields should be used.
forename1 String a-z, A-Z, - 70 characters max Forename of the subject, if the forename contains a space, it will be correctly matched to a name that contains a space.
middleName1 String a-z, A-Z, - 70 characters max Middle name of the subject, if the middle name contains a space, it will be correctly matched to a middle name that contains a space.
surname1 String a-z, A-Z, - 70 characters max Surname of the subject, if the surname contains a space, it will be correctly matched to a surname that contains a space.
dob1 String YYYY-MM-DD Date of birth of the subject. Month and day values can be substituted by a * wildcard character to match to any month or day.
name2 String a-z, A-Z, - 70 characters max Full name of the second person with each name element separated by a space, e.g. John Alan Smith. Should the forename, middle name or surname contain a spaces, the separate forename, middle name and surname fields should be used.
forename2 String a-z, A-Z, - 70 characters max Forename of the second person, if the forename contains a space, it will be correctly matched to a name that contains a space.
middleName2 String a-z, A-Z, - 70 characters max Middle name of the second person, if the middle name contains a space, it will be correctly matched to a middle name that contains a space.
surname2 String a-z, A-Z, - 70 characters max Surname of the second person, if the surname contains a space, it will be correctly matched to a surname that contains a space.
location String a-z, A-Z,0-9 - 70 characters max
building String a-z, A-Z,0-9 - 70 characters max Building definition, (optional) this can be a Building Number, Building Name, Sub Building Name or an Organisation Name.
street String a-z, A-Z,0-9 - 70 characters max Street definition (optional) for the address you wish to view.
locality String a-z, A-Z,0-9 - 70 characters max Locality definition (optional) for the address you wish to view. This can be the only input for the address.
town String a-z, A-Z,0-9 - 70 characters max Town definition (optional) for the address you wish to view. This can be the only input for the address.
county String a-z, A-Z,0-9 - 70 characters max County definition (optional) for the address you wish to view. This can be the only input for the address.
postcode String a-z, A-Z,0-9 - 70 characters max Postcode definition (optional) for the address you with to view. This can be the only input for the address. Partial entry can be used, for example CF or CF11.
alias Integer 0 or 1 Set to 1 to search common aliases of the name entered.
strictMiddle Integer 0 or 1 Set to 1 to only match to the middle name provided no match to no middle name if no middle name is provided.
withoutDOB Integer 0 or 1 Set to 1 to provide records without a DOB as well as records that specifically match the DOB provided.
withInitial Integer 0 or 1 Set to 1 to provide matches that contain only a first initial in place of a forename.
requestReference String a-z, A-Z,0-9 - 70 characters max Optional reference to assign to the search.