CVL KRA Download API

This document highlights the CVL KRA Download API details.

Objective

The CVL KRA Download API retrieves an applicant's existing KYC data from registered KYC Registration Agencies (KRAs). These include CVL, NDML, CAMS, Karvy, and Dotex.

API URL

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

API Endpoint

CVLKRADownload

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should Download 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)

Inputs

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

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
pan	Mandatory	The user's Permanent Account Number (PAN)	Not Applicable	Not Applicable
dateOfBirth	Mandatory	The user's date of birth	The input format for this parameter should be 'DD-MM-YYYY'	Not Applicable
KRAType	Mandatory	The KRA where the user's KYC records are maintained	"CVLKRA", "CAMS", "NDML", "KARVY", "DOTEX"	Not Applicable
fetchType	Mandatory	The category of information to be retrieved from the KRA	"I", "E", and "X" info I – For when DATA and IMAGE are required E – For when only DATA is required X – For when only IMAGE is required	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/CVLKRADownload' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "pan": "<Enter_the_PAN>",
    "dateOfBirth": "<Enter_the_Date_of_Birth_DD-MM-YYYY>",
    "KRAType": "<Enter_the_name_of_KRA>",
    "fetchType": "<Enter_I_E_or_X>"
}'

Success Response

The following code snippets demonstrate success responses from the API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "kycData": {
      "appIopFlg": "<Interoperable_Flag>",
      "appPosCode": "<Point_Of_Service_Code>",
      "appType": "<Applicant_Type>",
      "appKycMode": "<KYC_Mode_Code>",
      "appNo": "<Application_Number>",
      "appDate": "<Application_Date_in_DD-MM-YYYY_Format>",
      "appPanNo": "<PAN_Number>",
      "appPanCopy": "<PAN_Copy_Provided_Flag>",
      "appExmt": "<Exemption_Status>",
      "appExmtCat": null,
      "appExmtIdProof": "<Exemption_ID_Proof_Type>",
      "appIpvFlag": "<IPV_Completed_Flag>",
      "appIpvDate": "<IPV_Completion_Date_in_DD-MM-YYYY_Format>",
      "appGen": "<Gender_Code>",
      "appName": "<Full_Name_of_the_Applicant>",
      "appFName": "<Father's_Name>",
      "appRegno": "<Registration_Number>",
      "appDobDt": "<Date_Of_Birth_in_DD-MM-YYYY_Format>",
      "appCommenceDt": "<Commencement_Date_or_NA>",
      "appNationality": "<Nationality>",
      "appOthNationality": null,
      "appCompStatus": "<Compliance_Status_Code>",
      "appOthCompStatus": "<Other_Compliance_Status>",
      "appResStatus": "<Residential_Status>",
      "appResStatusProof": "<Residential_Status_Proof>",
      "appUidNo": null,
      "appCorAdd1": "<Correspondence_Address_Line_1>",
      "appCorAdd2": "<Correspondence_Address_Line_2>",
      "appCorAdd3": "<Correspondence_Address_Line_3>",
      "appCorCity": "<Correspondence_City>",
      "appCorPincd": "<Correspondence_Pincode>",
      "appCorState": "<Correspondence_State>",
      "appCorCtry": "<Correspondence_Country>",
      "appOffNo": null,
      "appResNo": null,
      "appMobNo": "<Mobile_Number>",
      "appFaxNo": null,
      "appEmail": "<Email_Address>",
      "appCorAddProof": "<Address_Proof_Type>",
      "appCorAddRef": "<Address_Reference_or_NA>",
      "appCorAddDt": "<Address_Date_or_Default>",
      "appPerAdd1": "<Permanent_Address_Line_1>",
      "appPerAdd2": "<Permanent_Address_Line_2>",
      "appPerAdd3": "<Permanent_Address_Line_3>",
      "appPerCity": "<Permanent_City>",
      "appPerPincd": "<Permanent_Pincode>",
      "appPerState": "<Permanent_State>",
      "appPerCtry": "<Permanent_Country>",
      "appPerAddProof": "<Permanent_Address_Proof>",
      "appPerAddRef": "<Permanent_Address_Reference_or_NA>",
      "appPerAddDt": "<Permanent_Address_Date_or_Default>",
      "appIncome": "<Income_Bracket>",
      "appOcc": "<Occupation_Type>",
      "appOthOcc": null,
      "appPolConn": null,
      "appDocProof": "<Document_Proof_Statement>",
      "appInternalRef": null,
      "appBranchCode": "<Branch_Code_or_NA>",
      "appMarStatus": "<Marital_Status>",
      "appNetwrth": null,
      "appNetworthDt": "<Networth_Date_or_Default>",
      "appIncorpPlc": "<Place_of_Incorporation_or_NA>",
      "appOtherinfo": null,
      "appFiller1": null,
      "appFiller2": "<Filler_Field_Value>",
      "appFiller3": "<Filler_Field_Value_or_NA>",
      "appRemarks": null,
      "appStatus": "<Application_Status_Code>",
      "appStatusdt": "<Application_Status_Date_in_DD-MM-YYYY_Format>",
      "appErrorDesc": null,
      "appDumpType": "<Dump_Type>",
      "appDnlddt": "<Download_Date_in_DD-MM-YYYY_Format>",
      "appKraInfo": "<KRA_Source>",
      "appSignature": null,
      "appAccOpendt": null,
      "appAccActivedt": null,
      "appAccUpdtdt": null,
      "appUidToken": null,
      "appVerNo": "<Version_Number>",
      "appFatcaApplicableFlag": "<FATCA_Flag>",
      "appFatcaBirthPlace": null,
      "appFatcaBirthCountry": null,
      "appFatcaCountryRes": null,
      "appFatcaCountryCityzenship": null,
      "appFatcaDateDeclaration": "<FATCA_Declaration_Date>"
    },
    "appPanSumm": {
      "appReqDate": "<PAN_Request_Timestamp>",
      "appOthkraBatch": "<Other_KRA_Batch_Number>",
      "appOthkraCode": "<Other_KRA_Code>",
      "appResponseDate": "<PAN_Response_Timestamp>",
      "appTotalRec": "<Total_Records>",
      "noOfFatcaAddlDtlsRecords": "<FATCA_Additional_Records_Count>"
    }
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

Parameter	Type	Description
status	string	The status of the API request
statusCode	integer	The HTTP status code of the response
result	object	Container for the response data
metaData	object	Metadata associated with the request
appIopFlg	string	Indicates whether the KYC application is associated with CVL or another KRA. Returns "I" if the application belongs to CVL, and "II" if it belongs to any other KRA
appPosCode	string	POS code of the Asset Management Company (AMC) on whose behalf the request is being updated
appType	string	Specifies whether the application is for an individual applicant or a non-individual applicant Note From this point forward, 'user' refers to an individual applicant, and 'organization' refers to a non-individual applicant
appKycMode	string	The mode of KYC verification. It could be one of the following: Normal(In-person) KYC e-KYC with OTP e-KYC with Biometric Online Data Entry and IPV Offline KYC - Aadhaar Digilocker
appNo	string	The unique number generated for each KYC application
appDate	string	The date on which the KYC application was submitted
appPanNo	string	The PAN of the user
appPanCopy	string	The value is 'yes' if the user's PAN card image was submitted; otherwise, the value is 'no'
appExmt	string	The value is 'no' if the user's PAN card image has been submitted, and 'yes' if user's exempted from submitting the PAN card
appExmtCat	string	The user was exempted from submitting their PAN card image due to one or more valid reasons. For the complete list of exemption criteria, please refer to this page
appExmtIdProof	string	The document used as Proof of Identity (when the user is exempted from submitting PAN as a valid ID Proof). For the complete list of valid ID proof documents, please refer to this page
appIpvFlag	string	The value is 'yes' if an In-Person Verification (IPV) was conducted for the KYC application; 'no' if not conducted, or 'exempted' if completed online
appIpvDate	string	The date when the IPV was conducted, if applicable
appGen	string	The gender of the user
appName	string	The full name of the user
appFName	string	The name of the user's father/husband
appRegno	string	The registration number of the organization
appDobDt	string	The date of birth of the user
appCommenceDt	string	The date when the organization commenced business
appNationality	string	The nationality of the user
appOthNationality	string	The user's nationality, if not Indian; for example, Argentina, Greece, etc
appCompStatus	string	The type of organization (Company Status). For the complete list of different types of valid organizations , please refer to this page.
appOthCompStatus	string	The status of the company, if 'Others' (as from appCompStatus's value)
appResStatus	string	The residential status of the user. It could be one of the following: Resident Individual Non-Resident Individual Foreign National QFI Eligible Foreign Investor - Category III
appResStatusProof	string	The address proof for a non-residential Indian or person of Indian origin. It could be one of the following documents: Passport PIO Card OCI Card
appUidNo	string	The last four digits of the UID/Aadhaar number of the user
appCorAdd1	string	The first line of the correspondence address. It includes the house number and the street name
appCorAdd2	string	The second line of the correspondence address. It includes the district name
appCorAdd3	string	The third line of the correspondence address. It includes the name of the corresponding state
appCorCity	string	The city of correspondence address
appCorPincd	string	The PIN code for correspondence address
appCorState	string	The state of correspondence address
appCorCtry	string	The country of correspondence address
appOffNo	string	The user's office contact number
appResNo	string	The user's residential contact number
appMobNo	string	The user's mobile phone number
appFaxNo	string	The fax number for the user
appEmail	string	The email address of the user
appCorAddProof	string	The document serving as proof of the correspondence address. For the complete list of accepted documents, please refer to this page
appCorAddRef	string	The identification number linked to the correspondence address proof document. For instance, if the Aadhaar card is provided as the address proof, the Aadhaar number serves as the reference ID
appCorAddDt	string	The validity date of the corresponding address proof, as specified in the address proof document
appPerAdd1	string	The first line of the permanent address. It includes the house number and the street name
appPerAdd2	string	The second line of the permanent address. It includes the name of the district
appPerAdd3	string	The third line of the permanent address. It includes the name of the state
appPerCity	string	The city of the permanent address
appPerPincd	string	The PIN code for the permanent address
appPerState	string	The state of the permanent address
appPerCtry	string	The country of the permanent address
appPerAddProof	string	The document serving as proof of the permanent address. For the complete list of accepted documents, please refer to this page
appPerAddRef	string	The identification number linked to the permanent address proof document. For instance, if the Aadhaar card is provided as the address proof, the Aadhaar number serves as the reference ID
appPerAddDt	string	The validity date of the permanent address proof, as specified in the address proof document
appIncome	string	The user's gross annual income, represented as a range. For more details on income slabs, please refer to this page
appOcc	string	The occupation of the user, specified by selecting a domain from this list
appOthOcc	string	The occupation details of the user, if 'Others' (as from appOcc's value)
appPolConn	string	The PEP status of the user, which they can select based on the category that applies to them. The categories are: Not Politically Exposed Politically Exposed Person (PEP) Related to a Politically Exposed Person(RPEP)
appDocProof	string	The details of the documents submitted by the user: whether they are self-certified copies or true copies of the documents
appInternalRef	string	Internal reference number for intermediaries
appBranchCode	string	The branch code to which the KYC is attached
appMarStatus	string	The marital status of the user, whether they are married or unmarried
appNetwrth	string	The net worth of the user or the organization
appNetworthDt	string	The net worth of the user or the organization as on date
appIncorpPlc	string	The place of incorporation of the organization, if applicable
appOtherinfo	string	Any additional information about the user or organization
appRemarks	string	The remarks associated with the application
appStatus	string	A code that represents the current status of the KYC application. The complete list of this can be accessed here
appStatusdt	string	The date when the KYC application was initiated
appErrorDesc	string	The description of any errors encountered
appDumpType	string	The type of data dump classification
appDnlddt	string	The date when data was downloaded
appKraInfo	string	The KRA information
appSignature	string	The Digital signature information
appAccOpendt	string	The date when account was opened
appAccActivedt	string	The date when account was activated
appAccUpdtdt	string	The date when account was last updated
appUidToken	string	The unique identifier token
appVerNo	string	The Version number of the application
appFatcaApplicableFlag	string	The confirmation on whether the application is subject to FATCA regulations
appFatcaBirthPlace	string	Place of birth for FATCA reporting
appFatcaBirthCountry	string	The country of birth for FATCA reporting
appFatcaCountryRes	string	The country of residence for FATCA reporting
appFatcaCountryCityzenship	string	The country of citizenship for FATCA reporting
appFatcaDateDeclaration	string	The date of FATCA declaration
appReqDate	string	The date and time of request submission
appOthkraBatch	string	The batch number for other KRA processing
appOthkraCode	string	The code for the other KRA agency
appResponseDate	string	The date and time when response was received
appTotalRec	string	The total number of records in the response
noOfFatcaAddlDtlsRecords	string	The number of additional FATCA detail records
requestId	string	The unique identifier for the request
transactionId	string	The identifier for the transaction

Error Responses

The following are some error responses from the API:

Invalid PAN format

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid PAN format"
}

Invalid DOB

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid DOB provided"
}

Invalid Request Details

{
    "status": "failure",
    "statusCode": "400",
    "message": "Invalid request details"
}

Duplicate Request

{
    "status": "failure",
    "statusCode": "400",
    "message": "Duplicate request"
}

Missing/Invalid credentials

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

Unsupported Media Type

{
    "status": "failure",
    "statusCode": "415",
    "message": "Unsupported media type"
}

Internal Server Error

{
    "status": "failure",
    "statusCode": "500",
    "message": "Internal Server Error"
}

Invalid Details

{
    "status": "failure",
    "statusCode": "500",
    "message": "Invalid User ID / PosCode / Password / Access Privilege Not Set"
}

Error Response Details

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

Status Code	Error Message	Error Description
400	Invalid PAN format	The PAN provided is not in the correct format. ('CCCCCDDDDC' format, where 'C' represents a character and 'D' represents a digit)
400	Invalid DOB provided	The date of birth provided is not valid
400	Invalid request details	The request details provided are incomplete or incorrect
400	Duplicate request	The request has already been submitted previously ???
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
415	Unsupported media type	The media type provided in the request is not supported
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
500	Invalid User ID / PosCode / Password / Access Privilege Not Set	The provided user credentials or access privileges are not correctly configured
500	Invalid Intermediary Code provided	The POS code of the AMC provided in the request is not valid

Application Status Codes

appStatus codes and their respective descriptions, representing the current status of the KYC Application.

Code	Description
00	DRAFT
01	SUBMITTED
02	DOCUMENTS RECEIVED
03	UNDER VERIFICATION
04	HOLD
06	DEACTIVATED
07	KRA Validated
11	OLD RECORD SUBMITTED
12	OLD RECORD DOCUMENT RECEIVED
13	OLD RECORD UNDER VERIFICATION
14	OLD RECORD ON HOLD
18	OLD RECORD VERIFIED BY CVLKRA
19	OLD RECORD REJECTED BY CVLKRA
21	OLD RECORD SCANNED COPY RECEIVED
24	OLD RECORD ON HOLD BY CVLKRA
28	OLD RECORD VERIFIED BY CVLKRA (WITHOUT DOCUMENTATION)
29	REJECTED DUE TO LATEST RECORD AVAILABILITY (TILL THE CASE IS APPROVED)
44	HOLD BY CVLKRA
98	VERIFIED BY CVLKRA
99	REJECTED BY CVLKRA
199	REJECTED - PRESENT IN NDML
299	REJECTED - PRESENT IN DOTEX
399	REJECTED - PRESENT IN CAMS KRA
499	REJECTED - PRESENT IN KARVY KRA
998	MF - VERIFIED BY CVLMF