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 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. Invoke the
ocr_transaction
method “create” command, supplying the subject’s surname, first name, and date of birth. - 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
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:-
|
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:-
|
ocr_status | The status of the verification. Possible values:-
|
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_status | The status of the verification. Possible values:-
|
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
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