API Documentation

The AgeVerifyUK API has two methods to allow you to programatically verify the age of a UK person. You can either check a single record or check multiple records in a CSV file.

Getting started - Using an API Key

To start using the API you will first need to sign up and get an API key from your Dashboard. Your API key should be kept private and not be included in web pages (use a Javascript Key instead).

To facilitate development you can set the api_key parameter to sandbox OR test to use the API in demo mode.

JSON/XML Output

Our API responds in XML format by default. Simply set the output parameter to 'json' to receive a JSON response (typically used in javascript/ajax solutions).

Example Live URL (outputted as JSON):

https://ageverifyuk.com/rest/rest.aspx?method=age_verification&api_key=[YOUR API KEY]&output=json&surname=[USER_INPUT]&forename=[USER_INPUT]&postcode=[USER_INPUT]&addr1=[USER_INPUT]

Example Development URL (outputted as JSON):

https://ageverifyuk.com/rest/rest.aspx?method=age_verification&api_key=sandbox&output=json&surname=[USER_INPUT]&forename=[USER_INPUT]&postcode=[USER_INPUT]&addr1=[USER_INPUT]

Using a Javascript Key

For security you should not use your API key from a client side call (e.g. javascript/AJAX). Use the javascript_key method to to create a secure temporary key that you can use to make client side requests to the AgeVerifyUK API.

Javascript Key Code Example

The following code example uses PHP to make a server side request to the AgeVerifyUK API to get a javascript key and an AJAX javascript request to do a single verification.

PHP Example - create a javascript key

			
//get_js_key.php

$url = 'https://ageverifyuk.com/rest/rest.aspx'
	. '?method=javascript_key'
	. '&api_key=test' 
	. '&domain=' . $_SERVER['HTTP_HOST']
	. '&ip_address=' . $_SERVER['REMOTE_ADDR']
	. '&output=json'
	. '&lifetime_minutes=10';

$json = file_get_contents($url);

header('Content-Type: application/json; charset=utf-8');
echo $json;
			
			
		

Example of Returned JSON when invoking 'javascript_key'

{"javascript_key":"4FHXcESzmDHX0BRvGJ-0_NTHvPrYIx-k3UBwW3Uu5Qt83gnYx8uJQaSEGcGMd5L7d8GbPy5pJVs4aSXvAVIw4-_5","lifetime_seconds":"1800","mode":"sandbox","status":"ok"}
	
	

Mandatory Parameters


Name Description
api_key Use your API key. Note that this method may only be invoked server-side.
domain Enter your domain (the request host parameter) on which the temporary Javascript key will be used.
lifetime_minutes The lifetime of the key; the maximum is 60 minutes.

Optional Parameters


Name Description
ip_address The remote IP address of the final user; if specified, the JavaScript key will only function for this IP address.
output Set to json for a JSON response; the default response is XML.

Returned Values


The XML response is contained within a <javascript_key_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code Returns the error code when the status is error. See below for error codes.
javascript_key The key which can now be used with client-side JavaScript, to connect to our servers. Note that this key is alphanumeric, plus the _ and - characters.

A single verification using a javascript_key

Make a request to get_js_key.php in your AJAX call to get a javascript key. Then use that key to call the single verfication method.

AJAX/JavaSript example of single verification (using javascript_key)

			
var surname = $("#surname");
var forename = $("#forename");
var postcode = $("#postcode");
var addr1 = $("#addr1");

$.ajax({
	url: 'get_js_key.php', //get_js_key.php created above
	dataType: 'json',
	success: function (result) {       
			
		if (result.status)
		{       
			$.ajax({
				url: 'https://ageverifyuk.com/rest/rest.aspx',
				dataType: 'json',
				data: {
					'method'   : "age_verification",
					'javascript_key'  : result.javascript_key,
					'domain' : "[YOUR WEBSITE DOMAIN]", //e.g. example.com
					'surname' : surname.val(),
					'forename' : forename.val(),
					'postcode' : postcode.val(),
					'addr1' : addr1.val(),
					'check_under_18' : 'true',
					'output'   : 'json'
				},
				success: function(result){
					if(result.validation_status == "NOT_FOUND") {
						$('#results-output').append('

'+forename.val()+' '+surname.val()+' was not found at the specificed address') }; if(result.validation_status == "FOUND_UNDER_18") { $('#results-output').append('

'+forename.val()+' '+surname.val()+' was found at the specified address, but we cannot confirm they are over 18') }; if(result.validation_status == "FOUND") { $('#results-output').append('

'+forename.val()+' '+surname.val()+' was found at the specified address and is over 18') }; } }); } } });

Example of Returned JSON when invoking 'age_verification'

{"validation_status":"FOUND","match_code_forename":"FULL","match_code_surname":"FULL","match_code_address":"PARTIAL","mode":"sandbox","status":"ok","api_version":"1.0.0.4"}
	

Note: although we use the most up to date data available it is possible that if a person has recently moved house they may not yet appear in the data. We recommend that an option is provided to allow people to attempt to verify their name at a previous address if we cannot verify them.

Mandatory Parameters

None of the parameters are case sensitive apart from the api key or javascript key.

Name Description
api_key or javascript_key Use your API key if invoking server-side. If invoking from the browser via JavaScript, generate a JavaScript key using the javascript_key method.
surname The surname of the subject. The case is irrelevant.
forename The forename of the subject.
postcode The postcode of the subject. Ideally this is the full UK postcode, but the method will check a partial code. If postcode_fuzzy is set to true, it will allow the final character of the postcode to be incorrect.

This can be in any case and any format

(such as YO98 9HZ or yo989HZ)
addr1 The first line of the address

Optional Parameters

Name Description
check_under_18 If set to "true" or "yes" or "y", the method will include persons who are under 18, but will return the status FOUND_UNDER_18 rather than FOUND. If you do not set this parameter, persons under 18 will return the status NOT_FOUND
addr2 The second line of the address
addr3 The third line of the address
place The locality
town The postal town
surname_fuzzy Set to true (default) to allow a slight fuzzy match.
forename_fuzzy Set to true (default) to allow a slight fuzzy match.
output Set to json for a JSON response; the default response is XML.

Returned Values


The XML response is contained within a <age_verification_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code Returns the error code when the status is error. See below for error codes.
checks_used The number of checks used in order to execute the request.
validation_status Set to:-

NOT_FOUND when the person could not be validated.

FOUND_UNDER_18 when a person under 18 has been validated

FOUND when a person has been validated.

TOO_MANY when the search parameters indicates more than one person sharing the full name.
match_code_surname

Describes how we matched the surname. Possible values:-

  • FULL when the surname perfectly matched.
  • FUZZY when the surname was slightly incorrect (or a known synonym).
match_code_forename

Describes how we matched the forename. Possible values:-

  • FULL when the forename matched.
  • FUZZY when the forename was slightly incorrect or was a known synonym.
match_code_address

Describes how we matched the address. Possible values:-

  • FULL when the address input perfectly matched the person's address.
  • PARTIAL when the address input partially matched. This occurs if some (but not all) of the words in the address, place and town fields were matched, and they were in the correct order.
  • (None) when the address was not used when matching the person.

Getting started - Using an API Key

To start using the API you will first need to sign up and get an API key from the My Account section.

Your API key should be kept private and not be included in web pages (use a Javascript Key instead).

To facilitate development you can set the api_key parameter to sandbox OR test to use the API in demo mode.

Usage

The age_verification_bulk method is a multi step asynchronous process that allows you to create a job, upload your data, start it processing and download the results once it has completed. For each stage in the process the first part of the API URL will remain the same but the command parameter must be changed depending on what part of the process you are in.

Example Live URL (bulk check):

https://ageverifyuk.com/rest/rest.aspx?method=age_verification_bulk&api_key=[YOUR API KEY]&command=[create|upload|start|progress|results|finalise]

This method allows for the verification of a list of UK persons, in a CSV containing at least these columns:

  • Forename
  • Surname
  • Address Line 1
  • Postcode

AgeVerifyUK will add a single RESULT column to the supplied CSV indicating the result of the check.

Result Column Values

Result Code Explanation
FOUND_OVER_18 The person has been verified
FOUND_UNDER_18 The person has been found but not verified as 18 or over.
NOT_FOUND The person was not found in our data
INVALID_POSTCODE The supplied postcode was invalid
INVALID_ADDRESS The supplied address was invalid
INSUFFICIENT_DATA There was insufficient information to be able to validate the person

Steps required


1. Create a new job

Create a job (also known as a transaction) and use the transaction_id returned to proceed with the bulk process.

Example PHP code:

			
function create_job() {

	$url = 'https://ageverifyuk.com/rest/rest.aspx'
	. '?api_key=[YOUR_APY_KEY]'
	. '&method=age_verification_bulk'
	. '&command=create';




	$result = simplexml_load_file($url);


	if($result->transaction_id) { //need this transaction_id for the other commands

		return $result;
	}

	return FALSE;	
	
}
		
		

Example XML Response

		<?xml version="1.0"?>
<age_verification_bulk_res>
	<mode>normal</mode>
	<status>ok</status>			
	<transaction_id>aBcDeF123456</transaction_id>
</age_verification_bulk_res>

Command 'create'

Mandatory Parameters

Name Description
api_key or javascript_key Use your API key if invoking server-side. If invoking from the browser via JavaScript, generate a JavaScript key using the javascript_key method.
command Must be set to create

Returned Values

The XML response is contained within a <age_verification_bulk_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code

Returns the error code when the status is error. See below for error codes.

transaction_id The ID of the job created.

2. Upload a CSV and specify columns

In this part of the process we set the command to 'upload' and use the transaction_id from step 1 above to POST your CSV to the AgeVerifyUK API. You also need to specify the zero based numerical index of what each column contains e.g. forename is in column 0, surname is in column 1 etc.

Example PHP code:

	
function set_columns($data, $forename, $surname, $addr1, $postcode, $type, $headers, $transaction_id, $fullname, $fulladdr) {

	$url = 'https://ageverifyuk.com/rest/rest.aspx'
	. '?api_key=[YOUR_APY_KEY]'
	. '&method=age_verification_bulk'
	. '&command=upload'
	. '&forename_column=' . $forename
	. '&surname_column=' . $surname
	. '&address1_column=' . $addr1
	. '&postcode_column=' . $postcode
	. '&fullname_column=' . $fullname
	. '&fulladdr_column=' . $fulladdr		
	. '&is_first_line_headers=' . $headers 
	. '&transaction_id=' . $transaction_id; //you get this is from create_job() above
	
	
		//we will POST the csv data
	
		$tch = curl_init();
		curl_setopt($tch, CURLOPT_URL, $url);
	
	// build $mypost using http_build_query, as recommended by folks on StackExchange
	// 
	
	$mypost_src = array(
		'csv' => $data
	);
	
	//
	$mypost = http_build_query($mypost_src);		
	
	//configure curl to do an HTTO POST
	//
	curl_setopt($tch, CURLOPT_POST, true);	        
		curl_setopt($tch, CURLOPT_RETURNTRANSFER, true);
		curl_setopt($tch, CURLOPT_SSL_VERIFYPEER, false);
		curl_setopt($tch, CURLOPT_POSTFIELDS, $mypost);

	curl_setopt($tch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded'));


		$post_res = curl_exec($tch);
		curl_close($tch);
		
	return TRUE;

}

	
	

Example XML Response


<?xml version="1.0"?>
<age_verification_bulk_res>
	<mode>normal</mode>
	<status>ok</status>	
	<transaction_id>aBcDeF123456</transaction_id>
</age_verification_bulk_res> 

Command 'upload'

Mandatory Parameters

Name Description
api_key or javascript_key Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method.
command Must be set to upload
transaction_id The ID of the job, as created by create.
type Must be set to res or bus to denote residential or business data. The data cannot be mixed.
csv_data The csv data. If you are using the REST API, you will need to invoke this method as a POST.
is_first_line_headers Set to Y if the first lineof the CSV is the column headers.
surname_column The column containing the surname, as a zero-based integer.
forename_column The column containing the forename, as a zero-based integer.
address1_column The column containing the first line of the address, as a zero-based integer.
address2_column The column containing the second line of the address, as a zero-based integer.
postcode_column The column containing the postcode, as a zero-based integer.

3. Start processing the CSV

Next set the command to 'start' to initialise the process.

Example PHP code:

			
function start_job($transaction_id) {

	$url = 'https://ageverifyuk.com/rest/rest.aspx'
	. '?api_key=[YOUR_APY_KEY]'
	. '&method=age_verification_bulk'
	. '&command=start'
	. '&transaction_id=' . $transaction_id;

	$result = simplexml_load_file($url);
	return $result;

}
			
			

Example XML Response



<?xml version="1.0"?>
<age_verification_bulk_res>
	<mode>normal</mode>
	<status>ok</status>	
	<transaction_id>aBcDeF123456</transaction_id>
</age_verification_bulk_res> 

Command 'start'

Mandatory Parameters

Name Description
api_key or javascript_key Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method.
command Must be set to start
transaction_id The ID of the job, as created by create

Returned Values

The XML response is contained within a <age_verification_bulk_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code

Returns the error code when the status is error. See below for error codes.

4. Monitor Progress

You can read the progress of the background processing using the command 'progress'.

Example PHP code:

			
function view_jobs_progress($transaction_id) {

	$url = 'https://ageverifyuk.com/rest/rest.aspx'
				. '?api_key=[YOUR_APY_KEY]'
	. '&method=age_verification_bulk'
	. '&command=progress'
	. '&transaction_id='.$transaction_id;

	$result = simplexml_load_file($url);
	return $result;
}
	
			

Example XML Response



<?xml version="1.0"?>
<age_verification_bulk_res>
	<mode>normal</mode>
	<status>ok</status>
	<transaction_id>aBcDeF123456</transaction_id>
	<percentage>100</percentage>
</age_verification_bulk_res> 

Mandatory Parameters

Name Description
api_key or javascript_key Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method.
command Must be set to progress
transaction_id The ID of the job, as created by create.
output Set to json if json is required.

Returned Values

The XML response is contained within a <age_verification_bulk_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code

Returns the error code when the status is error. See below for error codes.

percentage The progress. When "100" the job has finished processing and you may proceed to the next stage.

5. View Results

Once the process has completed you can view a summary of how many records were verified using the command 'results'. This command is free to use and you will only be charged if you choose to proceed to the next stage, 'finalise', which provides you with a download url.

Example PHP code:

			
function view_job_result($transaction_id) {

	$url = 'https://ageverifyuk.com/rest/rest.aspx'
				. '?api_key=[YOUR_APY_KEY]'
	. '&method=age_verification_bulk'
	. '&command=results'
	. '&transaction_id='.$transaction_id;

	$result = simplexml_load_file($url);
	return $result;
}
	
			

Example XML Response



<?xml version="1.0"?>
<age_verification_bulk_res>
	<mode>normal</mode>
	<status>ok</status>
	<total_records>6</total_records>
	<transaction_id>aBcDeF123456</transaction_id>
	<total_found>3</total_found>
	<start_time>2022-04-26 12:33</start_time>
	<original_file_name>bulk_test.csv</original_file_name>
</age_verification_bulk_res> 

Mandatory Parameters

Name Description
api_key or javascript_key Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method.
command Must be set to results
transaction_id The ID of the job, as created by create.

Returned Values

The XML response is contained within a <age_verification_bulk_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code

Returns the error code when the status is error. See below for error codes.

total_records The total number of rows in the CSV.
total_found The total number of rows that were able to be verified.
start_time Date and time process bulk age verification was started.
original_file_name The name of the file you uploaded.

6. Complete process and get a Download URL

Use the command 'finalise' to purchase the processed results and receive a download URL. This command will only charge you once if you call it repeatedly using the same transaction_id.

Example PHP code:

			
function view_job_result($transaction_id) {

	$url = 'https://ageverifyuk.com/rest/rest.aspx'
			. '?api_key=[YOUR_APY_KEY]'
	. '&method=age_verification_bulk'
	. '&command=finalise'
	. '&transaction_id='.$transaction_id;



	$result = simplexml_load_file($url);
	return $result;


}
	
			

Example XML Response



<?xml version="1.0"?>
<age_verification_bulk_res>
	<mode>normal</mode>
	<status>ok</status>	
	<chargeable>true</chargeable>
	<transaction_id>aBcDeF123456</transaction_id>
	<download_url>https://ageverifyuk.com/rest/rest.aspx?method=csv_download&job_id=aBcDeF123456</download_url>
</age_verification_bulk_res> 

Mandatory Parameters

Name Description
api_key or javascript_key Use your API key if invoking via server-side XML or SOAP. If using JSON, generate a JavaScript key using the javascript_key method.
command Must be set to finalise
transaction_id The ID of the job, as created by create.

Optional Parameters

Name Description
output Set to json for a JSON response; the default response is XML.
callback When using JSON, specify a JSONP wrapper in which the JSON response is to be wrapped.

Returned Values

The XML response is contained within a <age_verification_bulk_res> element.

Name Description
status Returns ok if the operation has succeeded, or error if an error has occurred; Returns the error_code for error details.
error_code

Returns the error code when the status is error. See below for error codes.

check_used The number of checks used in order to execute the request. For every record that is verfified we deduct 1 age check from your balance.
download_url The full URL from which the processed CSV may now be downloaded.

Get in touch with Age Verify UK

Email: info@AgeVerifyUK.com
Phone: 01904 567765

Please fill in contact form below and a member of our solutions team will get back to you.

Log in

Forgot password?


Don't have an account?

Sign up for AgeVerifyUK