CVL KRA Search and Verify API

This document highlights the CVL KRA Search and Verify API details.

Objective

The CVL KRA Search and Verify API authenticates the status of a user's Know Your Customer (KYC) record by cross-referencing their Permanent Account Number (PAN) against various KYC Registration Agency (KRA) databases.

API URL

https://ind-engine.thomas.hyperverge.co/v1/CVLSearchAndVerify

API Endpoint

CVLSearchAndVerify

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table provides the details of the parameters required for the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`appPanNo`	The unique 10-digit alphanumeric PAN	Mandatory	Format: 'CCCCCDDDDC' 'C' represents a character and 'D' represents a digit	Not Applicable

Sample Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/CVLSearchAndVerify' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "appPanNo": "<Enter_the_PAN>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "CVLSearchAndVerifyResponse": {
            "appPanInq": {
                "appPanNo": "<PAN_Number>",
                "appName": "<Full_Name>",
                "appStatus": "<Application_Status_Code>",
                "appStatusdt": "<Application_Status_DateTime>",
                "appEntrydt": "<Application_Entry_DateTime>",
                "appModdt": "",
                "appStatusDelta": "",
                "appUpdtStatus": "<Application_Update_Status_Code>",
                "appHoldDeactiveRmks": "",
                "appUpdtRmks": "",
                "appKycMode": "<KYC_Mode>",
                "appIpvFlag": "<IPV_Flag>",
                "appUboFlag": "",
                "appPerAddProof": "<Permanent_Address_Proof>",
                "appCorAddProof": "<Correspondence_Address_Proof>",
                "appStatusKra": "<KRA_Status>",
                "appStatusDesc": "<KRA_Status_Description>",
                "appUpdtStatusKra": "<KRA_Update_Status>",
                "appStatusUpdtDesc": "Not available (will not be displayed)"
            },
            "appPanSumm": {
                "batchId": "<Batch_ID>",
                "appResponseDate": "<Application_Response_DateTime>",
                "appTotalRec": "<Total_Records>"
            }
        },
        "appUpdtflg": "<Application_Update_Flag>",
        "status": "Not available (will not be displayed)"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
appPanNo	string	The 10 digit PAN of the user (same as the input request)
appName	string	The name of the PAN holder
appStatus	string	The three digit status code for a new KYC Application. The complete list of these codes can be referenced in the KYC Status Code Descriptions section.
appStatusDesc	string	The description of the new KYC application status
appUpdtStatus	string	The status of the KYC modification request represented as a three digit code. The complete list of these codes can be referenced in the KYC Modification Status Code Descriptions section.
appStatusUpdtDesc	string	The description of the modified KYC application status
appStatusdt	string	The date and time when the KYC status was last updated, displayed in the DD-MM-YYYY HH:MM:SS format
appEntrydt	string	The date and time when the KYC was created,displayed in the DD-MM-YYYY HH:MM:SS format
appModdt	string	The date and time of the latest modification of KYC record in Parent KRA, displayed in the DD-MM-YYYY HH:MM:SS format
appStatusDelta	string	The details of any missing data fields that prevented the KYC application from being verified
appHoldDeactiveRmks	string	The remarks for when a new KYC process, has either been put on hold or deactivated
appUpdtRmks	string	The remarks for when a modification request for KYC have been put on hold or rejected
appKycMode	string	The mode of KYC used for an application (e-KYC, Normal KYC, Digilocker or others)
appIpvFlag	string	The information pertaining to whether in-person verification was done, where Y indicates yes, N indicates no and E indicates exempted
appUboFlag	string	Indicates whether the applicant is an Ultimate Beneficial Owner (UBO)
appPerAddProof	string	The document used as proof of permanent address
appCorAddProof	string	The document used as proof of correspondence address
appStatusKra	string	This field indicates the KRA with which the PAN is associated, for a new KYC application
appUpdtStatusKra	string	This field indicates the KRA with which the PAN is associated, for a modified KYC application. A KYC application can only be modified once it has been registered and verified.
batchId	string	The unique batch ID assigned by the KRA for each batch
appResponseDate	string	The date and time when response is given by KRA, displayed in DD-MM-YYYY HH:MM:SS format
appTotalRec	string	The total number of records
appUpdtflg	string	This flag sets the Status field in the response and indicates the next steps for KYC application processing (e.g., Modify with Document, Interop Modification).

Error Responses

The following are some error responses from the API:

Invalid Input
Missing/Invalid credentials

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid PAN format",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Error Response Details

An error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	Invalid Input	The 10-digit PAN is not in the CCCCCDDDDC format
401	Missing/Invalid credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution

KYC Status Code Descriptions

note

The user KYC data could be present in any of the five KRA databases. A status code is represented as a three-digit string, 'XYZ', where;

'X' can be the following :
- 0 - CVLKRA
- 1 - NDML
- 2 - DOTEX
- 3 - CAMS
- 4 - KARVY
Charaters 'YZ' together represent the status description of the KYC application

With the following mapping in mind, please refer to the table below:

Output field: appStatus					Output field: appStatusDesc
CVLKRA	NDML	DOTEX	CAMS	KARVY	Status Description
000	100	200	300	400	Not Checked with respective KRA: The KRA-specific code, if returned, indicates that the user's KYC record could not be checked for that KRA database due to some failure.
001	101	201	301	401	Submitted : The data required for the KYC application has been submitted.
002	102	202	302	402	KRA Verified (KRA Registered) : The KYC application that has not yet been validated, due to inconsistencies in one or more of the following data fields: POA/POI data, e-mail address, phone number, PAN status and aadhaar linking status.
003	103	203	303	403	Hold: This code is specific for the documents uploaded for the KYC process. If any document is unclear or unreadable by the system, this code is displayed.
004	104	204	304	404	Rejected : The KYC has been rejected due to some errors with the uploaded data or documents
005	105	205	305	405	Not available : This code is displayed when: The verification documents have not been submitted The provided data does not match the verification documents submitted The uploaded documents are unclear or unreadable
006	106	206	306	406	Deactivated : The KYC record has been deactivated by the KRA, and no further action can be taken on it until reactivated
007	107	207	307	407	KRA Validated: The user's KYC is Validated. This status is assigned when the KRA can independently validate the POA/POI document with source data (such as Income Tax Department database on PAN, Aadhaar XML/DigiLocker/m-Aadhaar), and either PAN-Aadhaar linking was successful or Not Applicable, along with validated Email and/or Mobile number.
011	111	211	311	411	Existing KYC Submitted : An older KYC record has been submitted but is pending verification
012	112	212	312	412	Existing KYC Verified: The previously submitted KYC has been successfully verified and is valid
013	113	213	313	413	Existing KYC Hold : The older KYC record is on hold due to incomplete or incorrect documentation
014	114	214	314	414	Existing KYC Rejected: The older KYC record has been rejected due to errors in the application or mismatched documents
022					KYC REGISTERED WITH CVLMF: Indicates if the KYC is registered with CVL Mutual Funds
888	888	888	888	888	Not Checked with Multiple KRA: This code is displayed when more than one of the KRA databases can not be searched for KYC against a user's PAN
999	999	999	999	999	Invalid PAN NO Format:The 10-digit PAN is not in the CCCCCDDDDC format

KYC Modification Status Code Descriptions

note

The user KYC data could be present in any of the 4 KRAs. To refer to the following table, please note that a status code is structured as 'xyz', where;

'x' can be the following :
- 0 - CVLKRA
- 1 - NDML
- 2 - DOTEX
- 3 - CAMS
- 4 - KARVY
'yz' represents the status of the KYC application

With the following mapping in mind, please refer to the table below:

Output field: appUpdtStatus					Output field:appUpdtStatusDesc
CVLKRA	NDML	DOTEX	CAMS	KARVY	Status Description
000	100	200	300	400	Not Checked with Respective KRA
001	101	201	301	401	Modification Under Process
002	102	202	302	402	Modification Registered
003	103	203	303	403	Modification Hold
004	104	204	304	404	Modification Rejected
005	105	205	305	405	Not available (will not be displayed)
006	106	206	306	406	Deactivated
007	107	207	307	407	Modification Validated
888	888	888	888	888	Not Checked with Multiple KRA
005	105	205	305	405	If No value present (Blank), treat as Not available

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details​

Method - POST​

Headers​

Input​

Sample Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​

KYC Status Code Descriptions​

KYC Modification Status Code Descriptions​