Note: This version i.e. v1.2 is deprecated and support for this version will end on November 31st, 2018
Table of contents
- Identity Verification
- Get Request status
- Status Codes
- Signature Calculation
- Sample Codes
- Supported Languages
- Test IDs
- Revision history
Note: This version i.e. v1.2 is deprecated and support for this version will end on November 31st, 2018
Shufti Pro provides two modes of verification:
- Real-Time Verification
- Offline Verification
In Real time verification, your customer has to show their face and the required document in front of the camera. On the other hand in Offline Verification, you have an opportunity to provide your customer’s identity document to us via this API and we’ll send you the verification results back.
A typical real-time verification workflow looks like this:
- You send us your customer’s data to verify at one of our end points. We validate your request and send you a redirect URL so you can redirect your customer to our verification page or you can embed this in an iFrame.
- Your customer sees an instruction page. Upon clicking ‘Next’, the verification process starts.
- Your customer shows their face followed by the required document to the camera and the verification process begins in the background.
- Upon verification, your customer will be redirected to the given URL. Along with this URL, we’ll also send you the verification response via a callback. A callback is made before we redirect your customer to your redirect url.
- When you receive a verification response from us, you will also receive a field Signature. You need to verify this field before proceeding further. An example is given here.
In this mode, you only make a single call to our API with your customer’s Identity document and we send you the verification result back in response to this API call. You can provide us with this identity document either as an image or you can ask your customer to provide you with a recorded video, which you can forward to us. Therefore, for the Offline verification you can choose following methods:
- Still Image Verification (Your customer’s face and document image as a Base64 String)*
- Video Verification (A recorded video of your customer showing their face and identity document (details showing clearly in the camera))**
* Base64 string size shouldn’t be greater than 4MB for each image
** This video size shouldn’t be greater than 8MB
The Identity verification supports the following kinds of verification:
- General Purpose verification
- Driving license verification
- Passport verification
- ID Card verification
Your customer is provided with a list of ID documents to choose from such as passport, driving license or ID card. After the user chooses one particular document, they are requested to display the required document in front of the camera. The document's validity is ensured after cross checking the information provided in the request with that present on the document.
Your customer needs to display their Driving License. Shufti Pro verifies the validity of the driving license by cross checking the information (customer’s name and date of birth) provided in the request with that on the driving license.
Your customer needs to display their passport. The validity of the passport is verified by cross checking the provided information with that on the passport. For example, customer’s name and date of birth are cross checked to judged whether the passport shown is forged or authentic.
Your customer needs to display their Identity Card. It could be government, school and/or university issued ID card. Shufti Pro verifies the validity of such ID card by cross checking the information (customer's name and date of birth) provided in the request with that on the ID card.
How to make a verification request
You can make a request at the following endpoint with all the parameters defined below.
Endpoint: POST https://api.shuftipro.com/
|client_id||Required||Required||Client’s ID provided by Shufti Pro to you.|
|reference||Required||Required||Your Unique reference ID, which we will send you back with each response, so you can verify the request. Only alphanumeric values are allowed.|
|Optional||Optional||This parameter is used to notify your customer in case a verification result is delayed.|
|phone_number||Required||Required||Customer’s phone number with country code. Example: +440000000000|
|lang||Optional||Optional||Send ISO639-1 language code of your preferred language to display the verification screens accordingly. Please find a list of supported languages here.|
|country||Required||Required||Send the 2 characters long ISO 3166-1 alpha-2 country code of where your customer is from.|
|callback_url||Required||Optional||During a verification request, we make several server to server calls to keep you updated about the verification state. These states include: i) Customer lands on our verification page; ii) Verification process completes. This way you can update the request status at your end even if the customer is lost midway through the process.|
|redirect_url||Required||Required||Once the verification process completes, we redirect your customer to your given URL. In this redirect request, you’ll also get all the verification response values using HTTP POST method, so you can make your decision. Please verify the response’s signature value with your own calculated signature value.|
|verification_services||Required||Required||The JSON encoded array of all the data which you want us to verify using our different services. The key in this JSON encoded array will be the name of service which you want use in this verification request. e.g dob, first_name etc. All the available keys and the corresponding values are given below:
|verification_data||Optional||Required||If you want to perform an offline verification without redirecting your customer to us, you can send us the identity docs using this parameter. The JSON encoded array of all the data required in the offline verification. The following keys are allowed to send in the request. In the below table keys are listed in left side column and right side column has detail of each key.
|signature||Required||Required||SHA256 hash of all the request parameters in sorted order. The details are in the signature calculation section.|
Get Request status
Once a verification request is completed, you may request to this end point to get the verification status.
Endpoint: POST https://api.shuftipro.com/status
|client_id||Yes||Client’s ID provided by Shufti Pro to you. (ID must be in alphanumeric format)|
|reference||Yes||Your unique request reference that you have sent at the time of request. (a valid request reference that is associated with any request at the time it is made)|
|signature||Yes||Provide SHA256 hash of CONCATENATE(client_id, reference, secret_key)|
Find sample codes here.
The Shufti Pro API will send you two types of responses. First is the HTTP response sent against your request, and the second is the callback response, respectively. Both HTTP and callback responses will be in the JSON format and they will contain the following parameters:
|status_code||One of the status codes given here.|
|message||The description of status code. If the status code is SP2 then the message will be a redirect URL.|
|reference||Your unique request reference, which you provided us at the time of request, so that you can identify the response in relation to the request made.|
|signature||The SHA256 hash of CONCATENATE(status_code, message, reference, secret_key).|
Note: Callback response will be sent on the callback_url provided in the request callback_url parameter.
Status codes represent the status of the verification process (Success / Failure). The Shufti Pro Verification API uses the following status codes sent throughout when making any kind of verification request.
|SP2||Success! -- Contains the redirect url in message parameter.||Yes||Yes|
|SP11||Length Validation -- [parameter_name] maximum and minimum length limit is [min & max] characters.||Yes||Yes|
|SP14||Duplicate reference -- If a duplicate reference is provided.||Yes||Yes|
|SP15||Invalid client id -- Client id is invalid or not found.||Yes||Yes|
|SP16||Missing required parameter -- ["parameter_name"] is required but either missing or empty.||Yes||Yes|
|SP17||Invalid format -- ["parameter_name"] is not in the correct format.||Yes||Yes|
|SP18||Invalid signature -- Invalid request signature.||Yes||Yes|
|SP19||Invalid country code -- Invalid country code or country is not supported.||Yes||Yes|
|SP20||Invalid Phone No -- Invalid phone number is provided.||Yes||Yes|
|SP21||Invalid Method Name -- Given verification method is not supported.||Yes||Yes|
|SP22||Invalid checksum value.||Yes||Yes|
|SP23||Invalid DOB -- Date of birth is not valid.||Yes||Yes|
|SP24||Blocked Client -- Your account is not active.||Yes||Yes|
|SP25||Request Timeout -- Sends in callback when request timeouts.||Yes||Yes|
|SP26||User has been landed on verification page.||Yes||Yes|
|SP27||Request is already processed.||Yes||Yes|
|SP29||Invalid size. The size limit for ["parameter_name"] is ["size in MBs"].||Yes||Yes|
|SP30||A particular verification service is not enabled. Please contact to the support.||Yes||Yes|
|SP31||User closed his/her web browser.||Yes||Yes|
|SP32||Invalid request reference. Request not found.||Yes||Yes|
|SP33||Verification review pending.||Yes||Yes|
|SP34||Language (provided in the request) is not supported.||Yes||Yes|
|SP35||[parameter_name] not allowed with [method_name] verification method.||Yes||Yes|
|SP150||User clicked on verification cancel button||No||Yes|
|SP151||User disagreed from terms & condition||No||Yes|
|SP153||Your account doesn't have enough credits to perform this verification||Yes||Yes|
The request and response signature can be calculated as following:
- Sort all the request parameters (keys) in (ascending alphabetical order) and concatenate their values.
- Append the secret key at the end.
- Calculate the SHA256 hash of string (made in above 2 steps).
- Decode the JSON sent in the response body.
- Concatenate values of status_code, message, reference and secret key.
- Calculate the SHA256 hash of the string (made in above 2 steps).
Below are the sample codes in php, python & c# for the following verification methods:
- Online Identity verification
- Online Card Present verification
- Offline Identity verification
- Offline Card Present verification
Shufti Pro provides the users with a number of test documents. Customers may use these to test the demo, instead of presenting their actual information.
|March 14, 2018||1.0.1||Added new endpoint for get request status. https://api.shuftipro.com/status|
|March 26, 2018||1.0.2||Added lang parameter & supported languages list.|
|March 29, 2018||1.0.3||Added C# sample codes.|
|April 10, 2018||1.0.4||Added new supported languages.|
|July 10, 2018||1.0.5||Added new status codes.|
2016-18 © Shufti Pro Ltd.