Developer Guide

Age Verification API - integrate real-time UK age and identity verification directly into your application or workflow.

Before you start:

Create an Age Verify UK account.
Get your API key from your dashboard.

API endpoint

https://ageverifyuk.com/rest/rest.aspx

Your API key must be kept private and never included in client-side web pages. Use a javascript_key instead (see supplementary documentation). Set api_key to sandbox or test for development mode.

Choose a method

Select a verification method to view its full documentation.

age_verification

Data Matching

Verify a user-provided name and address against trusted sources like the Electoral Roll. Returns a real-time pass/fail result.

View documentation →

age_verification_bulk

Bulk Data Matching

Upload a CSV of names and addresses for batch verification. Process thousands of records asynchronously against our UK dataset.

View documentation →

Data Matching Pricing

Method: age_verification

Introduction

The method allows the validation of any UK person when a surname, forename, postcode and first line of address are all supplied. Your supplied data will be used to find a match within our vast UK dataset.

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]

Code Examples & Parameters

The following code example uses an AJAX javascript request with the javascript_key and user supplied name and address to do a single verification. Please view the supplementary documentation for instructions on getting a javascript_key.

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.

Code Example Parameter Reference

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 below
	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","transaction_id":"aBcDeF123456"}

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.
credits_used	The number of credits 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. If you receive a NOT_FOUND response you could try a previous address, if you have one available. Our data contains current and previous addresses for UK people.
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.

Error Codes

Name	Description
missing_surname	Mandatory parameter
missing_forename	Mandatory parameter
missing_addr1	Mandatory parameter
missing_postcode	Mandatory parameter
invalid_postcode	The postcode is not a valid UK postcode. Note that the format of the postode is flexible – upper, lower or mixed case is permitted and the space is not mandatory.

Bulk Age Verification of a CSV Pricing

Method: age_verification_bulk

Introduction

The age_verification_bulk method is a multi step asynchronous process that allows you to:

Create a job
Upload your data - a CSV containing a name, address and postcode
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):

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

If you receive a NOT_FOUND response you could try a previous address, if you have one available. Our data contains current and previous addresses for UK people.

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.

Code Example Parameter Reference

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>

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.

Code Example Parameter Reference

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
	
	
	$mypost_src = array(
		'csv' => $data
	);
	
	
	$mypost = http_build_query($mypost_src);		
	
	//configure curl to do an HTTP 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>

Name	Description
`api_key` or `javascript_key`	Use your API key if invoking via server-side XML. 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.

Code Example Parameter Reference

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>

Name	Description
`api_key` or `javascript_key`	Use your API key if invoking via server-side XML. 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

4. Monitor Progress

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

Code Example Parameter Reference

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>

Name	Description
`api_key` or `javascript_key`	Use your API key if invoking via server-side XML. 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.

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.

Code Example Parameter Reference

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>

Name	Description
`api_key` or `javascript_key`	Use your API key if invoking via server-side XML. 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.

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.

Code Example Parameter Reference

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>

Name	Description
`api_key` or `javascript_key`	Use your API key if invoking via server-side XML. 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.

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.

Supplementary Documentation

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

Code Example Parameter Reference

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"}

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.

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.

Date_Details Node Structure

This node structure is commonly used, but the node will actually be pertinently named, such as dob_details or created_details.

The nodes listed below are all children of the aforementioned node.

Name	Description
y	The year
m	The month 1-12
d	The day of the month 1-31
en	The date in a short English form D Mon YYYY, for example:- 1 May 2015 12 Jan 1974

Error Codes

Name	Description
method_not_subscribed	You are not subscribed to the specified method.
missing_(param)	The named mandatory parameter is missing. For example:- missing_api_key indicates that the parameter api_key is missing.
invalid_(param)	The named parameter is in an invalid format. For example:- invalid_api_keyapi_key value is invalid.
expired_javascript_key	The javascript_key value, used during client-side request, has expired.
http_referrer_missing	When a javascript_key is in use, the http referrer request header was missing, so the domain cannot be authenticated.
client_ip_address_not_allowed	When a javascript_key is in use, the IP address permitted to use the key does not match the final user’s IP address.
client_domain_not_allowed	When a javascript_key is in use, the domain from which the request has originated does not match the specified domain.
unauthorised_ip_address	When not using a JavaScript key, the IP address from which the request has originated does not match any of the permitted IP addresses set the control panel.
insufficient_credit	You do not have sufficient credit to use this method.
too_many	The request returned more records than can be included in the response. More information 18 ©Simunix Ltd 2022 should be supplied to allow the search to be narrowed.
no_record	The request returned no records. We return an error code in preference to the more verbose option of returning an empty result set.
invalid_address	The address given in the input parameters is invalid.
failed	A general error has occurred. In normal operation you should never see this error; please use our backup facility
no_database	A general error has occurred. In normal operation you should never see this error.

Developer Guide

Choose a method

Data Matching

Bulk Data Matching

Data Matching Pricing

Introduction

JSON/XML Output

Example Live URL (outputted as JSON):

Example Development URL (outputted as JSON):

Code Examples & Parameters

A single verification using a javascript_key

AJAX/JavaSript example of single verification (using javascript_key)

Example of Returned JSON when invoking 'age_verification'

Mandatory Parameters

Optional Parameters

Returned Values

Error Codes

Bulk Age Verification of a CSV Pricing

Introduction

Example Live URL (bulk check):

Result Column Values

Steps required

1. Create a new job

Example PHP code:

Example XML Response

Command 'create'

Mandatory Parameters

Returned Values

2. Upload a CSV and specify columns

Example PHP code:

Example XML Response

Command 'upload'

Mandatory Parameters

3. Start processing the CSV

Example PHP code:

Example XML Response

Command 'start'

Mandatory Parameters

Returned Values

4. Monitor Progress

Example PHP code:

Example XML Response

Mandatory Parameters

Returned Values

5. View Results

Example PHP code:

Example XML Response

Mandatory Parameters

Returned Values

6. Complete process and get a Download URL

Example PHP code:

Example XML Response

Mandatory Parameters

Optional Parameters

Returned Values

Supplementary Documentation

Using a Javascript Key

Javascript Key Code Example

PHP Example - create a javascript key

Example of Returned JSON when invoking 'javascript_key'

Mandatory Parameters

Optional Parameters

Returned Values

Date_Details Node Structure

Error Codes

Get in touch

Information