Additional APIs

Aadhaar ( Digilocker )

This API helps you fetch the Digilocker-verified documents for your customers. End users need not have a Digilocker account in advance to fetch the documents. If an individual does not have a Digilocker account, we will create an account on the go and fetch the documents. Experience for both types of customers will be exactly the same.

The First API call creates a redirection link to go through the OTP Process. The second API call fetches the verification result using personId and requestId generated in the first step.

Integration Steps

STEP 1. INTEGRATION

To integrate with this API and fetch documents from Digilocker you just need to make a single API call to fetch a particular document.

Every document needs different input parameters for searching and downloading.

STEP 2. REDIRECTING END USERS TO DIGILOCKER

Response will include a re-direction URL that will redirect to Digilocker. This URL will need to be loaded for the end-user.

Input of Aadhaar number and OTP needs to be done in the Digilocker environment and must not be handled on the client end.

STEP 3. HANDLING DIGILOCKER RESPONSE

Once you redirect the customers to the redirect_url, they should be prompted for the Digilocker sign-up/sign-in page, and then on successful sign-in, we will fetch the relevant docs and send the success/failure response over the catch hook whitelisted on the dashboard. Refer to the Webhook ( Realtime Updates ) section below for the webhook payloads.

Success / Failure Responses can also be fetched from the Get Verification Status Api. Although we would recommend using webhook approach to get real time updates of the verification process.

Kindly make sure, your integration doesnt mask the redirection URL in any way.

Get Redirection URL

Method and URL

POST : https://api-dev.springscan.springverify.com/v4/databaseCheck

Headers

Name	Description
tokenKey	XXXXX ( To be generated from dashboard )

Example Request

curl --location 'https://api-dev.springscan.springverify.com/v4/databaseCheck' \
--header 'tokenKey: XXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
    "docType": "ind_aadhaar",
    "name_match_threshold": 50,
    "success_parameters": [
        "id_number"
    ],
    "manual_input": {
        "id_number": "XXXXXXX",
        "name": "XXXXXX",
        "dob": "YYYY-MM-DD",
        "address": "XXXXYYYYZZ"
    },
    "sourceIsDigilocker": true
}'

Example Response

{
    "message": "You dont have an active Digilocker token. Please use the below redirection to generate a digilocker Token",
    "redirection_url": "<redirection_url>",
    "personId": "XXXXXXXXX",
    "requestId": "XXXXXXXXXXX"
}

This API creates a redirection link to go through the Digilocker flow which sends OTP to the registered Mobile Number and creates a new personId if not mentioned in the request.

Get Verification Results

Method and URL

POST : https://api-dev.springscan.springverify.com/v4/databaseCheck

Headers

Name	Description
tokenKey	XXXXX ( To be generated from dashboard )

Request Parameters

sourceIsDigilocker Source is Digilocker to be true
personId pass from the first step ( personid should be of same instance that of request_id).
request_id pass from the first step.
success_parameter specifies the parameter that would determine whether verification based on matching of input with source was success or failure. If no parameter is specified the default parameter would be id_number which means that status will be successful if ‘id_number’ is matching with source.

Success Parameters

Success Parameters	Values
Default	id_number
Supported	id_number, name

Response Description

matching_ocr_to_source: NA

matching_manual_to_source:

id_number : true/false based on matching with source.
name : is a score in the range of 0-100.
address: is a score in the range of 0-100.

personId and request_id are mandatory parameters.

It is recommended to whitelist one catchhook at our end to get realtime updates about the verification process. The same can be done by logging onto the dashboard.

Get Verification Status

Method and URL

GET : https://api-dev.springscan.springverify.com/v4/digilocker/getVerificationStatus/<request_id>

Headers

Name	Description
tokenKey	XXXXX ( To be generated from dashboard )

Example Request

curl --location 'https://api-dev.springscan.springverify.com/v4/digilocker/getVerificationStatus/XXXXXXX' \
--header 'tokenKey: XXXXXXXX'

Example Response

{
    "verificationStatus": "SUCCESS / USER_CANCELLED / AUTHENTICATION_FAILED / USER_DENIED_ACCESS / VERIFICATION_PENDING ",
    "data": {
        "configuration": {
            "api_config": {
                "api_action": "verify",
                "api_doc_type": "ind_aadhaar",
                "api_doc_face": "N/A",
                "api_status": "success",
                "api_status_code": 200,
                "api_status_code_description": "Successful Response for the given inputs.",
                "source": "digilocker",
                "request_id": "XXXXXXXXXX",
                "created_at": "XXXXXXXXXX",
                "completed_at": "XXXXXXXXXX",
                "person_id": "XXXXXXXXXX"
            },
            "success_config": {
                "name_match_threshold": 50,
                "success_parameter": ["id_number"],
                "success_config_description": "Verification will be successful if id_number is matched."
            }
        },
        "output": {
            "ocr": "N/A",
            "source": {
                "id_number": "XXXXXXXXXXXX",
                "id_number_masked": "XXXXXXXX1234",
                "name": "XXXXXX",
                "dob": "YYYY-MM-DD",
                "gender": "male",
                "address": "XXXXXXXXXX",
                "pincode": "XXXXXX",
                "base_64_face": "<base64_image>"
            },
            "derived_based_on_source": {
                "yob": "YYYY",
                "age": 30,
                "aadhaarholder_is_minor": false
            }
        },
        "matching": {
            "ocr_to_source": "N/A",
            "manual_to_source": {
                "id_number": true,
                "name": 100,
                "dob": true,
                "address": 80
            }
        },
        "status": {
            "got_source_response": true,
            "status_matching": "success",
            "status_matching_based_on": "Manual Input",
            "status_matching_message": {
                "id_number": "verified"
            }
        }
    }
}

This API is used to get current verification status of the request.

RequestId is a mandatory param.

The data object is only populated when verificationStatus is SUCCESS. For all other statuses, data will be null.

Response Description

verificationStatus : current status of the verification request. Possible values are SUCCESS, USER_CANCELLED, AUTHENTICATION_FAILED, USER_DENIED_ACCESS and VERIFICATION_PENDING.
output.source : details of the document fetched from Digilocker.
matching.manual_to_source : matching of the manual_input provided in the request against the source. id_number and dob are true/false. name and address are scores in the range of 0-100.
status.status_matching : success / failed based on matching of the success_parameters.
status.status_matching_message : verified / not_verified for each success_parameter requested.

Webhook ( Realtime Updates )

It is recommended to whitelist a webhook ( catch hook ) URL on the dashboard to receive realtime updates of the verification process. Once the end user completes ( or abandons ) the Digilocker flow, we will POST the result to the whitelisted URL.

Delivery

Name	Description
Method	POST ( to the webhook URL whitelisted on the dashboard )
Content-Type	application/json

Events

Event	Description
SUCCESS	Verification completed successfully. Payload carries the full verification result.
USER_CANCELLED	End user cancelled the Digilocker flow.
AUTHENTICATION_FAILED	Digilocker authentication failed.
USER_DENIED_ACCESS	End user denied access to the document.
REDIRECTION_FAILED	Digilocker redirection failed.
WEBHOOK_TEST_PUSH	Test event triggered while configuring the webhook URL on the dashboard.

Example Payload ( SUCCESS )

On success, the webhook payload carries the same data object returned by the Get Verification Status API, along with the requestId.

{
    "configuration": {
        "api_config": {
            "api_action": "verify",
            "api_doc_type": "ind_aadhaar",
            "api_doc_face": "N/A",
            "api_status": "success",
            "api_status_code": 200,
            "api_status_code_description": "Successful Response for the given inputs.",
            "source": "digilocker",
            "request_id": "XXXXXXXXXX",
            "created_at": "XXXXXXXXXX",
            "completed_at": "XXXXXXXXXX",
            "person_id": "XXXXXXXXXX"
        },
        "success_config": {
            "name_match_threshold": 50,
            "success_parameter": ["id_number"],
            "success_config_description": "Verification will be successful if id_number is matched."
        }
    },
    "output": {
        "ocr": "N/A",
        "source": {
            "id_number": "XXXXXXXXXXXX",
            "id_number_masked": "XXXXXXXX1234",
            "name": "XXXXXX",
            "dob": "YYYY-MM-DD",
            "gender": "male",
            "address": "XXXXXXXXXX",
            "pincode": "XXXXXX",
            "base_64_face": "<base64_image>"
        },
        "derived_based_on_source": {
            "yob": "YYYY",
            "age": 30,
            "aadhaarholder_is_minor": false
        }
    },
    "matching": {
        "ocr_to_source": "N/A",
        "manual_to_source": {
            "id_number": true,
            "name": 100,
            "dob": true,
            "address": 80
        }
    },
    "status": {
        "got_source_response": true,
        "status_matching": "success",
        "status_matching_based_on": "Manual Input",
        "status_matching_message": {
            "id_number": "verified"
        }
    },
    "requestId": "XXXXXXXXXX"
}

Example Payload ( Failure Events )

For all non-success events, the payload contains the event details along with the requestId.

{
    "api_status_code": 400,
    "api_status_message": "User cancelled the process.",
    "api_status_description": "USER_CANCELLED",
    "requestId": "XXXXXXXXXX"
}

Payload Description

The full verification data is only sent when the event is SUCCESS. Failure events carry only the api_status fields describing the failure.
requestId : the requestId generated in the Get Redirection URL step. Use it to correlate the webhook with your request, or to fetch the result again via the Get Verification Status API.
api_status_description : matches the verificationStatus values of the Get Verification Status API ( USER_CANCELLED, AUTHENTICATION_FAILED, USER_DENIED_ACCESS ).
VERIFICATION_PENDING is never delivered over the webhook. It is only returned by the Get Verification Status API while the verification is still in progress.
Your endpoint should respond with a 2xx status code to acknowledge receipt.

Selfie Quality Detection

Method and URL

POST : https://api-dev.springscan.springverify.com/v4/checkFaceQuality

Headers

Name	Description
Authorization	Bearer + JWT ( Generated from Login API )
Token	XXXXX
tokenKey	XXXXX ( To be generated from dashboard )

You can also run this API by passing the tokenKey (generated from Dashboard) in the headers instead of Authorization and token.

Example Request

curl --location --request POST 'https://api-dev.springscan.springverify.com/v4/checkFaceQuality' \
--header 'tokenKey: XXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
    "selfie_image" : "<selfie_url>",
    "personId": "XXXXXXXXXX"
}'

Example Response

{
    "api_config": {
        "api_action": "selfie_quality",
        "api_doc_type": "face_image",
        "api_doc_face": "N/A",
        "api_status": "success",
        "api_status_code": 200,
        "api_status_description": "Okay",
        "request_id": "N/A",
        "created_at": "XXXXXXXXX",
        "completed_at": "XXXXXXXXXXXX",
        "person_id": "XXXXXXXXXXXXXXXXXXX"
    },
    "success_config_matching": "N/A",
    "input_ocr": {
        "selfie_image": "<selfie_image>"
    },
    "input_manual": "N/A",
    "output_ocr": "N/A",
    "output_source": {
        "face_detected": "XXXX",
        "face_quality": "XXXX",
        "is_live": "XXXX",
        "face_coverage_score": "XX",
        "multiple_facces_detected": "XXXX",
        "selfie_url": "<selfie_image>"
    },
    "output_source_derived": "N/A",
    "matching_manual_to_source": "N/A",
    "matching_ocr_to_source": "N/A",
    "status": {
        "got_source_response": true,
        "status_matching": false,
        "status_based_on": "N/A",
        "status_matching_message": "Selfie Face recognition failed"
    }
}

Returns quality of selfie image

Input

Selfie_image : url of selfie image.
Supported file type : png, jpeg, jpg, webp.

Output

Face_detected : boolean output which represents whether was detected in the image .
Face_quality : representation regarding the quality of face in the image which can be good or bad.
Is_live : boolean output which represents whether the face detected in the image was stationary or in motion.
Face_coverage_score : contains value between 0-100 and represents extent of face in the input image.
Multiple_faces_detected : boolean output which represents whether multiple faces were detected in the image.
Selfie_url : url of the image which was provided as input.