A step by step guide about the verification processes, required key parameters, HTTP codes, supported formats and processing events.
Switch branches/tags
Nothing to show
Clone or download

README.md

Introduction

Shufti Pro has designed this Verification API document for its customers that have signed up for our next-generation service pack. This document will explain various kinds of verification services included in this service pack, how they are provided and what kind of data is required from our clients to perform these verifications successfully.

Shufti Pro’s AI & HI hybrid technology ensures 99.6% accurate results and quickest response time.

Shufti Pro’s API supports two verification types, i.e. on-site and off-site.

On-site Verification (Through an iFrame)

On-site verification means that the customer will come on Shufti Pro’s site and perform verification there. They will not perform it through the merchant’s site. Shufti Pro will collect the information directly from customer.

  • With OCR

Merchant provides us with the keys, not the data. Example: name: “ ”. This means that the merchant has opted for name verification but has not sent any data. We have to extract the data, from the user’s provided documents, at our end, and then verify it as well. Consult This Document for complete On-site Verification with OCR.

  • Without OCR

Merchant provides us with the keys, along with the data. Example: issue_date: “2016-07-16”. This means that the merchant has opted for issue date verification with the verification data. We have to simply verify that information, no data extraction is required. Consult This Document for complete On-site Verification without OCR.

Off-site Verification

Off-site verification means that the customer will not come on Shufti Pro’s site to get verified. They will do it through the merchant’s platform. Merchant will collect the information and send us the data for verification. Merchant provides us with the proofs (images/videos). We will not collect them directly from the user.

  • With OCR

In off-site verification with OCR means that the merchant has not provided us proofs (images/videos) and also no data in some keys. In this verification Shufti Pro will perform extraction of data from those proofs and finally verify the data. Consult This Document for complete Off-site Verification with OCR.

  • Without OCR

If Merchant gives us the data in keys as well as all the proofs required then Shufti Pro just have to verify the data. No customer interaction takes place in this kind of verification. Consult This Document for complete Off-site Verification without OCR.

Authorization

The Shufti Pro Verification API authenticates clients with a Basic Auth header. Provide your Client ID as Username and Secret Key as Password. This header is required in every request that will be made to the API.

Fields Required Description
username Yes Enter Client ID as username.
password Yes Enter your Secret Key as password.

Verification Request Sample

Run in Postman

POST /api/ HTTP/1.1
Host: shuftipro.com


Content-Type: application/json


Authorization: Basic NmI4NmIyNzNmZjM0ZmNlMTlkNmI4WJRTUxINTJHUw== 

{
	"reference": "",
	"country": "",
	"language": "",
	"email": "",
	"callback_url": "",
	"redirect_url": "",

	"verification_mode": "",

	"face": {
		"proof": ""
	},

	"document": {
		"proof": "",
		"additional_proof": "",
		"supported_types": [],
		"name": "",
		"dob": "",
		"document_number": "",
		"expiry_date": "",
		"issue_date": ""
	},

	"address":{
		"proof":"",
		"full_address":"",
		"name": "",
		"supported_types":[]
	},
	
	"consent":{
		"proof":"",
		"supported_types":[],
		"text":"",
	},

	"phone": {
		"phone_number": "",
		"random_code": "",
		"text": ""
	},

	"background_checks": {
		"name": "",
		"dob": ""
	}
}

Verification Request

Run in Postman

Shufti Pro is performing variety of verifications for its customers. Our diverse services suite allows us to validate the identity of users through facial verification, documents verification and address verification. We can also check the authenticity of customised documents like official IDs and perform background checks for AML compliance. A mix of various service modules can also be acquired to perform multifaceted verifications like facial and document verification can help you perform a thorough KYC procedure.

Whenever a request for verification from a customer is received, the intelligent system of Shufti Pro ascertains the nature of verification through following parameters. These parameters enable Shufti pro to identify its customers, authenticity of client credentials, read client data, what kind of verification is required (off-site or on-site) and what material is being sent to perform that verification. Some of these parameters are necessarily required while others are optional.

Request Parameters

It is important to note here that each service module is independent of other and each one of them is activated according to the nature of request received from you. There are a total of six services which include face, document, address, consent, phone and background_checks.

All verification services are optional. You can provide Shufti Pro a single service or mixture of several services for verifications. All keys are optional too. If a key is given in document or address sevice and no value is provided then OCR will be performed for those keys.

  • reference

    Required: Yes
    Type: string
    Minimum: 6 characters
    Maximum: 250 characters

    This is the unique reference ID of request, which we will send you back with each response, so you can verify the request. Only alphanumeric values are allowed. This reference can be used to get status of already performed verification requests.

  • country

    Required: Yes
    Type: string
    Length: 2 characters

    Send the 2 characters long ISO 3166-1 alpha-2 country code of where your customer is from. Please consult Supported Countries for country codes.

  • language

    Required: No
    Type: string
    Length: 2 characters

    Send the 2 characters long language code of your preferred language to display the verification screens accordingly. Please consult Supported Languages for language codes. Default language english will be selected if this key is missing in the request.

  • email

    Required: No
    Type: string
    Minimum: 6 characters
    Maximum: 128 characters

    This field represents email of the end-user. If it is missing in a request, than Shuftpro will ask the user for its email in an on-site request.

  • callback_url

    Required: Yes
    Type: string
    Minimum: 6 characters
    Maximum: 250 characters

    During a verification request, we make several server to server calls to keep you updated about the verification state. This way you can update the request status at your end even if the customer is lost midway through the process.

  • redirect_url

    Required: No
    Type: string
    Minimum: 6 characters
    Maximum: 250 characters

    Once an on-site verification is complete, User is redirected to this link after showing the results.

  • verification_mode

    Required: No
    Type: string
    Accepted Values: any, image_only, video_only

    Verification mode defines how would you like us to verify your request, through a video or an image. If you specify video_only then the verification process would require a video to complete the face, document, address or consent verification process. In case you specify image_only then then verification process can be completed through still images. If you don't provide this parameter at all then the image_only mode will be set.

  • allow_offline

    Required: No
    Type: string
    Accepted Values: 0, 1
    Default Values: 1

    This parameter allows users to upload images or videos in case of nonavailability of a functional webcam.If value: 0, users can capture photos/videos with the camera only.

  • face

    The easiest of all verifications is done by authenticating the face of the users. In case of on-site verification, end-user will have to show their face in front of a webcam or camera of their phone that essentially makes it a selfie verification.

    • proof

    Required: No
    Type: string
    Image Format: JPG, JPEG, PNG, PDF Maximum: 16MB
    Video Format: MP4/MOV Maximum: 20MB

    Provide valid BASE64 encoded string. Leave empty for an on-site verification.

  • document

    Shufti Pro provides document verification through various types of documents. The supported formats are passports, ID Cards, driving licenses and debit/credit cards. You can opt for more than 1 document type as well. In that case, Shufti Pro will give an option to end-users to verify their data from any of the given document types.

    In case of off-site verification, you can provide more than 1 document image and use “additional proof” parameter for this. This is to ensure that the required credentials are easily visible e.g. a document might have name and image of individual at the front but the date of birth of that person is printed at the back of the document or on another page of the passport. If you opt for both facial and document verification, face of individual from document will be used to validate uploaded selfie.

    • proof

    Required: No
    Type: string
    Image Format: JPG, JPEG, PNG, PDF Maximum: 16MB
    Video Format: MP4/MOV Maximum: 20MB

    Provide valid BASE64 encoded string. Leave empty for an on-site verification.

    • additional_proof

    Required: No
    Type: string
    Image Format: JPG, JPEG, PNG, PDF Maximum: 16MB
    Video Format: MP4/MOV Maximum: 20MB

    Provide valid BASE64 encoded string. Leave empty for an on-site verification.

    • supported_types

    Required: Yes Type: Array

    Document verification have two parameters: proof and additional_proof. If these two are not set or empty, it means that it should be an on-site verification. You can provide any one, two or more types of documents to verify the identity of user. For example, if you opt for both passport and driving license, then your user will be given an opportunity to verify data from either of these two documents. Please provide only one document type if you are providing proof of that document with the request. All supported types are listed below.

    Supported Types
    passport
    id_card
    driving_license
    credit_or_debit_card

    Example 1 ["driving_license"]
    Example 2 ["id_card", "credit_or_debit_card", "passport"]

    • name

    Required: No
    Type: object

    In name object used in document service, first_name is required if you don't want to perform OCR of the name parameter. Other fields are optional.

    Example 1 { "first_name" : "John", "last_name" : "Doe" }
    Example 2 { "first_name" : "John", "last_name" : "Doe", "fuzzy_match" : "1"}

    • first_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark. Example John'O Harra

    • middle_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark.
    Example Carter-Joe

    • last_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark. Example John, Huricane Jr.

    • fuzzy_match

    Required: No
    Type: string
    Value Accepted: 1

    Provide 1 for enabling a fuzzy match of the name. Enabling fuzzy matching attempts to find a match which is not a 100% accurate.

    • dob

    Required: No
    Type: string
    Format: yyyy-mm-dd

    Provide a valid date. Please note that the date should be before today. Example 1990-12-31

    • document_number

    Required: No
    Type: string
    Minimum: 2 characters
    Maximum: 100 chracters

    Allowed Characters are numbers, alphabets, dots, dashes, spaces, underscores and commas. Examples 35201-0000000-0, ABC1234XYZ098

    • issue_date

    Required: No
    Type: string
    Format: yyyy-mm-dd

    Provide a valid date. Please note that the date should be before today. Example 2015-12-31

    • expiry_date

    Required: No
    Type: string
    Format: yyyy-mm-dd

    Provide a valid date. Please note that the date should be after today. Example 2025-12-31

  • address

    Address of an individual can be verified from the document but they have to enter it before it can be verified from an applicable document image. Supported document formats include ID cards, utility bills and bank statements.

    • proof

    Required: No
    Type: string
    Image Format: JPG, JPEG, PNG, PDF Maximum: 16MB
    Video Format: MP4/MOV Maximum: 20MB

    • supported_types

    Required: Yes
    Type: Array

    Provide any one, two or more document types in proof parameter in Address verification service. For example, if you choose id_card and utility_bill, then the user will be able to verify data using either of these two documents. Please provide only one document type if you are providing proof of that document with the request. Following is the list of supported types for address verification.

    Supported Types
    id_card
    passport
    driving_license
    utility_bill
    bank_statement
    rent_agreement
    employer_letter
    insurance_agreement
    tax_bill

    Example 1 [ "utility_bill" ]
    Example 2 [ "id_card", "bank_statement" ]

    • full_address

    Required: No
    Type: string
    Minimum: 2 characters
    Maximum: 250 chracters

    Allowed Characters are numbers, alphabets, dots, dashes, spaces, underscores, hashes and commas.

    • name

    Required: No
    Type: object

    In name object used in address service, first_name is required if you don't want to perform OCR of the name parameter. Other fields are optional.

    Example 1 { "first_name" : "John", "last_name" : "Doe" }
    Example 2 { "first_name" : "John", "last_name" : "Doe", "fuzzy_match" : "1"}

    • first_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark. Example John'O Harra

    • middle_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark.
    Example Carter-Joe

    • last_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark. Example John, Huricane Jr.

    • fuzzy_match

    Required: No
    Type: string
    Value Accepted: 1

    Provide 1 for enabling a fuzzy match of the name. Enabling fuzzy matching attempts to find a match which is not a 100% accurate.

  • consent

    Customised documents/notes can also be verified by Shufti Pro. Company documents, employee cards or any other personalised note can be authenticated by this module. You can choose handwritten or printed document format but only one form of document can be verified in this verification module. Text whose presence on the note/customized document is to be verified, is also needed to be provided.

    • proof

    Required: No
    Type: string
    Image Format: JPG, JPEG, PNG, PDF Maximum: 16MB
    Video Format: MP4/MOV Maximum: 20MB

    • supported_types

    Required: Yes
    Type: array

    Text provided in the consent verification can be verified by handwritten documents or printed documents.

    Supported Types
    handwritten
    printed

    Example 1 ["printed"]
    Example 2 ["printed", "handwritten"]

    • text

    Required: Yes
    Type: string
    Minimum: 2 characters
    Maximum: 100 chracters

    Provide text in the string format which will be verified from a given proof.

  • phone

    Verify the phone number of end-users by sending a random code to their number from Shufti Pro. Once the sent code is entered into the provided field by end-user, phone number will stand verified. It is primarily an on-site verification and you have to provide phone number of the end-user to us, in addition to the verification code and the message that is to be forwarded to the end-user. Shufti Pro will be responsible only to send the message along with verification code to the end user and verify the code entered by the end-user.

    • phone_number

    Required: No
    Type: string
    Minimum: 2 characters
    Maximum: 64 chracters

    Allowed Characters: numbers and plus sign at the beginning. Provide a valid customer’s phone number with country code. Shufti Pro will directly ask the end-user for phone number if this field is missing or empty.

    • random_code

    Required: No
    Type: string
    Minimum: 2 characters
    Maximum: 10 chracters

    Provide a random code. If this field is missing or empty. Shufti Pro will generate a random code.

    • text

    Required: No
    Type: string
    Minimum: 2 characters
    Maximum: 100 chracters

    Provide a short description and random code in this field. This message will be sent to customers. This field should contain random_code. If random_code field is empty than Shufti Pro will generate a random code and append the code with this message at the end.

  • background_checks

    It is a verification process that will require you to send us the full Name of end user in addition to date of birth. Shufti Pro will perform AML based background checks based on this information. Please note that the name and dob keys will be extracted from document service if these keys are empty.

    • name

    Required: No
    Type: object

    In name object used in background checks service, first_name required and other fields are optional.

    Example 1 { "first_name" : "John", "last_name" : "Doe" }
    Example 2 { "first_name" : "John", "middle_name" : "Carter", "last_name" : "Doe"}

    • first_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark. Example John'O Harra

    • middle_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark.
    Example Carter-Joe

    • last_name

    Required: No
    Type: string
    Minimum: 1 character
    Maximum: 32 chracters

    Allowed Characters are alphabets, - (dash), comma, space, dot and single quotation mark. Example John, Huricane Jr.

    • dob

    Required: No
    Type: string
    Format: yyyy-mm-dd

    Provide a valid date. Please note that the date should be before today. Example 1990-12-31

Status Request sample

Run in Postman

POST /api/ HTTP/1.1
Host: shuftipro.com


Content-Type: application/json


Authorization: Basic NmI4NmIyNzNmZjM0ZmNlMTlkNmI4WJRTUxINTJHUw== 

{     
	"reference" : "17374217"
}

Status Request

Once a verification request is completed, you may request at status end point to get the verification status. You’ll have to provide reference ID for status request and you will be promptly informed about the status of that verification.

  • reference

    Required: Yes
    Type: string
    Minimum: 6 characters
    Maximum: 250 characters

    This is the unique reference ID of request, which we will send you back with each response, so you can verify the request. Only alphanumeric values are allowed.

Responses

Verification Response

The Shufti Pro Verification API will send you two types of responses if a request for verification is made. First is the HTTP response sent against your request, and the second is the callback response. Both HTTP and callback responses will be in the JSON format with header application/json. The response header also includes a key sp_signature. This key is used for validating the source of response. Be sure to validate the request by generating signature and matching it with sp_signature value from the response header.
Responses will contain the following parameters:

  • 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.
  • event

    This is the request event which shows status of request. Event is changed in every response.

    Please consult Events for more information.

  • error

    Whenever there is an error in your request, this parameter will have the details of that error.
  • token

    This is the unique request token of the request.
  • verification_url

    A URL is generated for your customer to verify there documents. It is only generated in case of on-site request.
  • verification_result

    It is only returned in case of a valid verification. This includes results of each verification.

    1 means accepted
    0 means declined
    null means not processed

    Check verification.accepted and verification.declined responses in Events section for a sample response.

  • verification_data

    It is only returned in case of a valid verification. This object will include the all the gathered data in a request process.

    Check verification.accepted and verification.declined responses in Events section for a sample response.

  • declined_reason

    This parameter will have the reason due to which a verification has been declined, and is only returned in this case in the callback URL.
Note: Callback response will be sent on the callback_url provided in the request callback_url parameter.

Sample Response

Content-Type: application/json


sp_signature: NmI4NmIyNzNmZjM0ZmNl

{
    "reference":"17374217",
    "event":"request.pending",
    "error":"",
    "verification_url":"https://shuftipro.com/api/verify/474f51710fb60fdf9688f44ea0345eda28a9f55212a83266fb5d237babff2"
}

Status Response

The Shufti Pro Verification API will send a JSON response if a status request is made. Make sure to validate the request by generating signature and matching it with sp_signature value from response header.

  • 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.
  • event

    This is the request event which shows status of request. Event is changed in every response.

    Please consult Events for more information.

Note: request.invalid response with HTTP status code 400 means the request is invalid.

Sample Response



Content-Type: application/json


sp_signature: NmI4NmIyNzNmZjM0ZmNl

{
    "reference": "17374217",
    "event": "request.invalid"
}

Response Signature

Every HTTP and Callback responses will be in application/json with a key sp_signature in the header. It can be used to validate the source of the request. Make a signature using the following procedure:

  1. Concatinate Secret Key at the end of the response string. (i.e. response + secret_key).
  2. Take SHA256 of concatinated string.
  3. Match the SHA256 string with sp_signature value from the header of the response.

In short, make signature as hash('sha256', response . your_secret_key) and match it with the signature provided in the header in sp_signature key.

HTTP Status Codes and Events

Instant Capture & Verification API uses conventional HTTP response codes to indicate the success or failure of an API request. Every response is generated in JSON with a specific HTTP code. Go to Status Codes for a complete list of status codes. Events are sent in responses which show the status of request. These events are sent in both HTTP and callback responses. Please consult Events for a complete list of events.

Supported Browsers and Devices

In case of on-site verification, a verification page is shown to users. This page is supported on the following list of browsers.

Browsers Minimum Version/SDK
Chrome (Recommended) 65
Firefox (Recommended) 58
Safari 8
Opera 52
Internet Explorer 11
Edge 16

Here a list of supported operating systems on mobile devices.

Mobile OS Minimum Version/SDK
Android 6.0 (Marshmallow)
iOS 10

Test IDs

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.


Revision History

Date Description
06 Dec 2018 Minimum characters limit is set to 1 for first, middle and last name
29 Nov 2018 Update POSTMAN collection link, remove format key and add supported_types key for consent service in POSTMAN collection.
29 Oct 2018 Changed format key to Supported_types in consent Service.
29 Oct 2018 Allowed PDF documents as proofs in image_only and any verification modes.
26 Nov 2018 Add allow_offline key in request parameters.
22 Oct 2018 Add declined reason key in response.
17 Oct 2018 Update Test IDs for demo/test verifications.
09 Oct 2018 1. Last name field is optional in all name objects.
2. Added signature in response headers to validate the source of responses.