OCR ID Verification

A facility to verify an uploaded photographic ID

Verify an uploaded photographic ID (such as driving licence or passport) with Optical character recognition (OCR) / Biometric checking.

Overview

We currently offer two methods (age_verify and person_verify) which use our UK person data (including electoral roll) to verify a subject.

The photo ID verification process may be used in conjunction with this method, or as a stand-alone verification task.

The photo ID verification process allows the use of valid photographic ID (such as driving licence, or passport), to verify the identity of a person.

We offer two scenarios by which the photo ID verification process may be implemented.

Photo ID OCR verification Flow Chart
View Full Size

Photo ID Verification Process Details

This section describes the photo ID verification process in detail, including the multiple start options, and the two techniques available to progress through the process.

Preparing The Photo ID Verification Process

The photo ID verification process requires the existence of a transaction_ID.

The following sections describe how that transaction_ID is obtained.

Following a Verification Method

When one of the verification methods listed below has been invoked, a unique transaction_ID is part of the response returned by T2A.

The transaction_ID is returned by:-

  • person_verify
  • age_verification

In both methods, the ID is in a node named transaction_ID, in the root of the response object.

Without a Verification Method

The photo ID verification process may be progressed without the previous use of a verification method, explained below:-

  1. 1. Invoke the ocr_transaction method “create” command, supplying the subject’s surname, first name, and date of birth.
  2. 2. The above invocation will supply a transaction_ID to be used in the photo ID verification process
Initialising The Photo ID Verification Process

Once the transaction_ID has been obtained, by one of the means described above, the ocr_transaction method must be invoked, using the “set” command. The following parameters are optional:-

  • Set docscan_type to ocronly (the default) or biometric, to select the type of photo ID verification that will be executed.
  • Set callback_url to the URL which the system will invoke, when using a callback (see below).

The “set” command returns a verification_url; which is the URL used to send the user to the document upload user interface

Sending The User to the Document Upload User Interface

There are two discrete techniques available:- using a callback or launch a new process for the verification. These are described below

When Using a Callback

When using a callback, the developer will inform the photo ID verification process to where it should return, when the verification process is completed.

The photo ID verification process will invoke the callback URL as a GET, with the transaction_ID appended to the query string, if there is one, or will create a new query string.

Example usage:-

  • The website verify_me.dummy prepares the transaction_ID as described above.
  • The ocr_transaction method “set” command is invoked, with
    callback_url = https://verify_me.dummy/doneverify/
  • The photo ID verification is invoked
  • The photo ID verification process, when completed, invoked the callback URL, but appends ?transacton_id=[32 char transaction ID] to the invoked URL.
  • The callback URL, having been invoked, “knows” the transaction_ID.
  • The invoked callback URL may now proceed to complete the process (see below)
When Not Using a Callback

When not using a callback it is necessary to launch a new process (or new window) in which the actual photo ID verification will take place. Simultaneously, the original process will wait until the new process has completed; when this has been completed, it will progress to the completion process.

Example usage:-

  • The website verify_me.dummy prepares the transaction_ID as described above.
  • The ocr_transaction method “set” command is invoked, with no callback URL.
  • The website launches a new window, in which the photo ID verification is invoked
  • The original window will “wait” for the new window to complete the verification. It does this by repeatedly invoking the ocr_transaction “get” command, using the transaction_ID, with a suitable delay between each invocation, until the ocr_status is set.
  • The new window, launched above, is now terminated.
  • The original process may now proceed to complete the process (see below).

Completing The Photo ID Verification Process

When Using a Callback

As described above, the callback URL has been invoked as a GET, with the transaction_ID supplied to the URL.

The callback URL may invoke ocr_transaction “get” command, to read the ocr_status of the verification.

The appropriate output message can now be displayed, using the verification status.

When Not Using a Callback

Following completion of the verification by the “child” process, the main process may invoke ocr_transaction “get” command, to read the ocr_status of the verification.

The appropriate output message can now be displayed, using the verification status

API method to use: ocr_transaction (docscan_type: ocronly)
|
Credits per use: 120
ocr_transaction (docscan_type: biometric)
|
Credits per use: 200

Security

Please note that when using a method from a client-side request (normally JSON) you must use a javascript_key which is a short-lived secure session key derived using the method of that name. Never use your API key in a request sent from a web browser (using JQuery or Ajax directly), in order to protect your prepaid credits. The javascript_key method is documented on t2a.io

This method supports the OCR facility, added to T2A in late 2022, to offer additional verification functionality.

Any invocation of these methods will create a transaction ID (in a node called transaction_id)

This transaction ID can then be used with the ocr_transaction method. Additionally, a transaction may be manually created.

Commands

The individual operations of this method are selected using the mandatory command parameter.

Command 'create'

Manually create a transaction instance. This is only used when not referencing a transaction_id returned by the age_verification method.

Mandatory Parameters

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 create

Returned Values

The XML response is contained within a <ocr_transaction_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 transaction ID of the instance created by this invocation.

Command 'set'

Set values for an existing transaction.

Note that the credit balance is checked, and if the balance is insufficient, method will fail, and the insufficient_credit error will be returned.

Mandatory Parameters

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 set
transaction_id The ID of the transaction. This is obtained either from the original invocation of the age_verification method, or from an earlier invocation of the set command in this method.

If not supplied, a new transaction is created

Optional Parameters

Name Description
callback_url The redirection URL to which the end user will be redirected when the process is complete.
docscan_type The type of verification.

Permissibe values:-
  • ocronly (the default value)
  • biometric
surname Store the surname. This is only used where the transaction was created by the 'create' command.

The surname is encrypted using AES-256
forename Store the forename. This is only used where the transaction was created by the "create" command.

The forename is encrypted using AES-256

Returned Values

The XML response is contained within a <ocr_transaction_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 transaction ID
credit_balance The account credit balance
callback_url The redirection URL to which the end user will be redirected when the process is complete.
docscan_type The type of verification.

Permissibe values:-
  • ocronly (the default value)
  • biometric
ocr_status The status of the verification.

Possible values:-
  • VALIDATED
  • NOTVALIDATED
  • (an error message from our OCR partner)
verification_url The URL to which the end user is to be redirected, to start the OCR process.
dob A date_details node showing the date of birth, where this has been previously set in the transaction.

Example XML

		
<?xml version="1.0"?>
<ocr_transaction_res>
	 <mode>normal</mode>
	 <status>ok</status>
	 <t2a_version_number>3.5.0.9</t2a_version_number>
	 <transaction_id>wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U</transaction_id>
	 <callback_url/>
	 <docscan_type/>
	 <ocr_status/>
	 <verification_url>https://t2a.io/upload/ocr/wKVrW6dhYPMBEA0iQTuJ_u9YQx_L1fOvVqQ1AOboPS_U
	 </verification_url>
	 <dob>
		 <y>1983</y>
		 <m>3</m>
		 <d>16</d>
		 <en>16 Mar 1983</en>
	 </dob>
</ocr_transaction_res>

Command 'get'

Return the search parameters, and and additional information, relating to this transaction ID.

Mandatory Parameters

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 get
transaction_id The ID of the transaction. This is obtained either from the original invocation of the relevant T2A verification method, or from an invocation of the set command in this method.

Returned Values

The XML response is contained within a <ocr_transaction_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 transaction ID
callback_url The redirection URL to which the end user will be redirected when the process is complete.
docscan_type The type of verification.

When set, these values may be present:-
  • ocr_only
  • biometric
ocr_status The status of the verification.

Possible values:-
  • VALIDATED
  • NOTVALIDATED
  • (an error message from our OCR partner)
verification_url The URL to which the end user is to be redirected, to start the OCR process.
dob A date_details node showing the date of birth, where this has been previously set in the transaction

Example XML

		
<?xml version="1.0" encoding="utf-8" ?>
<ocr_transaction_res>
	 <status>ok</status>
	 <mode>normal</mode>
	 <t2a_version_number>3.6.1.2</t2a_version_number>
	 <transaction_id>e387b084fb29ca191d907038a7c24e08</transaction_id>
	 <callback_url/>
	 <docscan_type/>
	 <ocr_status/>
	 <verification_url>https://t2a.io/upload/ocr/e387b084fb29ca191d907038a7c24e08</verification_url>
	 <dob>
		 <y>1993</y>
		 <m>11</m>
		 <d>16</d>
		 <en>16 Nov 1993</en>
	 </dob>
</ocr_transaction_res>

 

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.

Next Steps...

We will give you a unique API key to allow you to test the method using credits on your T2A account.

If you do not have an account you will first need to sign up

 

Get in touch

 

Other related API methods:

Age Verification - check if a person is 18 or over
Person Verification - check if someone exists
Search the Electoral Roll (edited version)
Check if a person is deceased