CAMS KRA Download API

The following document highlights the details of the CAMS KRA Download API.

API Description

Objective

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

Input	Output
PAN, date of birth, KRA type, and fetch type	The complete KYC data of the customer in a JSON response, including personal details, address information, contact details, and application status

API URL

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

API Endpoint

CAMSKRADownload

Overview

The CAMS KRA Download 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.

Method - POST

Authentication

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

Headers

Header	Mandatory / Optional	Description	Input Format
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 CAMS KRA Download API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
pan	Mandatory	string	The user's Permanent Account Number (PAN)	Format: 'CCCCCDDDDC' where 'C' represents a character and 'D' represents a digit	Not Applicable
dateOfBirth	Mandatory	string	The user's date of birth	DD-MM-YYYY	Not Applicable
signRequired	Optional	char	Indicates whether a signature is required. Set the value to "N" if signature is not required; otherwise, signature is considered by default	N	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/CAMSKRADownload' \
--header 'Content-Type: application/json' \
--header 'appID: <Enter_the_HyperVerge_appId>'\
--header 'appKey: <Enter_the_HyperVerge_appKey>'\
--header 'transactionID: <Enter_the_HyperVerge_transactionID>' \
--data-raw '{
    "pan": "<Enter_the_PAN>",
    "dateOfBirth": "<Enter_the_Date_of_Birth_DD-MM-YYYY>",
    "signRequired": "<N>"
}'

Success Response

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

{
     "status": "success",
    "statusCode": "200",
    "result": {
        "posCode": "<Point_Of_Service_Code>",
        "appNo": "<Application_Number>",
        "date": "<Application_Date_in_DD-MM-YYYY_Format>",
        "exmt": "<Exemption_Status>",
        "exmtCategory": "<Exemption_Category>",
        "exmtIdProof": "<Exemption_ID_Proof_Type>",
        "ipvFlag": "<IPV_Flag>",
        "ipvDate": "<IPV_Date_in_DD-MM-YYYY_Format>",
        "gender": "<Gender>",
        "name": "<Name_Of_The_User>",
        "firtName": "<Father_Name>",
        "dob": "<Date_Of_Birth_in_DD-MM-YYYY_Format>",
        "regNo": "<Registration_Number>",
        "commenceDate": "<Commencement_Date_in_DD-MM-YYYY_Format>",
        "nationality": "<Nationality>",
        "othNationality": "<Other_Nationality>",
        "compStatus": "<Company_Status>",
        "othCompStatus": "<Other_Company_Status>",
        "resStatus": "<Residential_Status>",
        "statusProof": "<Status_Proof>",
        "pan": "<PAN_Number>",
        "panCopy": "<PAN_Copy_Flag>",
        "uidNo": "<UID_Number>",
        "corAddress1": "<Correspondence_Address_Line_1>",
        "corAddress2": "<Correspondence_Address_Line_2>",
        "corAddress3": "<Correspondence_Address_Line_3>",
        "corCity": "<Correspondence_City>",
        "corPincode": "<Correspondence_Pincode>",
        "corState": "<Correspondence_State>",
        "corCountry": "<Correspondence_Country>",
        "offNo": "<Office_Number>",
        "resNo": "<Residential_Number>",
        "mobileNo": "<Mobile_Number>",
        "faxNo": "<Fax_Number>",
        "email": "<Email_Address>",
        "corAddressProof": "<Correspondence_Address_Proof>",
        "corAddRef": "<Correspondence_Address_Reference>",
        "corAddDt": "<Correspondence_Address_Date_in_DD-MM-YYYY_Format>",
        "perAddress1": "<Permanent_Address_Line_1>",
        "perAddress2": "<Permanent_Address_Line_2>",
        "perAddress3": "<Permanent_Address_Line_3>",
        "perCity": "<Permanent_City>",
        "perPincode": "<Permanent_Pincode>",
        "perState": "<Permanent_State>",
        "perCountry": "<Permanent_Country>",
        "perAddressProof": "<Permanent_Address_Proof>",
        "perAddressRef": "<Permanent_Address_Reference>",
        "perAddDt": "<Permanent_Address_Date_in_DD-MM-YYYY_Format>",
        "income": "<Income_Bracket>",
        "occupation": "<Occupation>",
        "otherOccupation": "<Other_Occupation>",
        "polConn": "<Political_Connection_Status>",
        "docProof": "<Document_Proof_Status>",
        "internalRef": "<Internal_Reference>",
        "branchCode": "<Branch_Code>",
        "maritalStatus": "<Marital_Status>",
        "networth": "<Networth>",
        "networthDate": "<Networth_Date_in_DD-MM-YYYY_Format>",
        "incorpPLC": "<Incorporation_Place>",
        "otherInformation": "<Other_Information>",
        "remarks": "<Remarks>",
        "accOpenDate": "<Account_Open_Date_in_DD-MM-YYYY_Format>",
        "accActiveDate": "<Account_Active_Date_in_DD-MM-YYYY_Format>",
        "accUpdateDate": "<Account_Update_Date_in_DD-MM-YYYY_Format>",
        "status": "<Application_Status_Code>",
        "statusDate": "<Status_Date_in_DD-MM-YYYY_HH:MM:SS_Format>",
        "errorDescription": "<Error_Description>",
        "dumpType": "<Dump_Type>",
        "dnlDdt": "<Download_Date_in_DD-MM-YYYY_HH:MM:SS_Format>",
        "iopFlag": "<Interoperable_Flag>",
        "kraInfo": "<KRA_Information>",
        "signature": "<Signature>",
        "kycMode": "<KYC_Mode>",
        "uidToken": "<UID_Token>",
        "versionNo": "<Version_Number>",
        "fatcaApplicableFlag": "<FATCA_Applicable_Flag>",
        "fatcaBirthPlace": "<FATCA_Birth_Place>",
        "fatcaBirthCountry": "<FATCA_Birth_Country>",
        "fatcaCountryRes": "<FATCA_Country_Of_Residence>",
        "fatcaCountryCityzenship": "<FATCA_Country_Of_Citizenship>",
        "fatcaDateDeclaration": "<FATCA_Date_Of_Declaration_in_DD-MM-YYYY_Format>",
        "type": "<Applicant_Type>",
        "resStatusProof": "<Residential_Status_Proof>",
        "appResDate": "<Application_Response_Date_in_DD-MM-YYYY_HH:MM:SS_Format>"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code of the response
result	object	Container for the response data
result.posCode	string	POS code of the Asset Management Company (AMC) on whose behalf the request is being updated
result.appNo	string	The unique number generated for each KYC application
result.date	string	The date on which the KYC application was submitted
result.exmt	string	The value is 'N' if the user's PAN card image has been submitted, and 'Y' if user's exempted from submitting the PAN card
result.exmtCategory	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
result.exmtIdProof	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
result.ipvFlag	string	The value is 'Yes' if an In-Person Verification (IPV) was conducted for the KYC application; 'No' if not conducted, or 'eKYC' if completed online
result.ipvDate	string	The date when the IPV was conducted, if applicable
result.gender	string	The gender of the user. The valid values are Female Male Transgender
result.name	string	The full name of the user
result.firtName	string	The name of the user's father/husband
result.dob	string	The date of birth of the user
result.regNo	string	The registration number of the organization
result.commenceDate	string	The date when the organization commenced business
result.nationality	string	The nationality of the user. The valid values are Indian Others
result.othNationality	string	The user's nationality, if not Indian
result.compStatus	string	The type of organization (Company Status). For the complete list of different types of valid organizations, please refer to this page
result.othCompStatus	string	The status of the company, if 'Others'
result.resStatus	string	The residential status of the user. For the complete list of valid values for the parameter, please refer to this page
result.statusProof	string	The proof of residential status
result.pan	string	The PAN of the user
result.panCopy	string	The value is 'Yes' if the user's PAN card image was submitted; otherwise, the value is 'No'
result.uidNo	string	The last four digits of the UID/Aadhaar number of the user
result.corAddress1	string	The first line of the correspondence address
result.corAddress2	string	The second line of the correspondence address
result.corAddress3	string	The third line of the correspondence address
result.corCity	string	The city of correspondence address
result.corPincode	string	The PIN code for correspondence address
result.corState	string	The state of correspondence address. For the complete list of allowed values, please refer to this page
result.corCountry	string	The country of correspondence address. For the complete list of countries, please refer to this page
result.offNo	string	The user's office contact number
result.resNo	string	The user's residential contact number
result.mobileNo	string	The user's mobile phone number
result.faxNo	string	The fax number for the user
result.email	string	The email address of the user
result.corAddressProof	string	The document serving as proof of the correspondence address. For the complete list of accepted documents, please refer to this page
result.corAddRef	string	The identification number linked to the correspondence address proof document
result.corAddDt	string	The validity date of the corresponding address proof
result.perAddress1	string	The first line of the permanent address
result.perAddress2	string	The second line of the permanent address
result.perAddress3	string	The third line of the permanent address
result.perCity	string	The city of the permanent address
result.perPincode	string	The PIN code for the permanent address
result.perState	string	The state of the permanent address. For the complete list of allowed values, please refer to this page
result.perCountry	string	The country of the permanent address. For the complete list of countries, please refer to this page
result.perAddressProof	string	The document serving as proof of the permanent address. For the complete list of accepted documents, please refer to this page
result.perAddressRef	string	The identification number linked to the permanent address proof document
result.perAddDt	string	The validity date of the permanent address proof
result.income	string	The user's gross annual income, represented as a range. For more details on income slabs, please refer to this page
result.occupation	string	The occupation of the user, specified by selecting a domain from this list
result.otherOccupation	string	The occupation details of the user, if 'Others'
result.polConn	string	The PEP status of the user
result.docProof	string	The details of the documents submitted by the user Self Certified Copies Submitted (Originals Verified) True Copies of Documents Received
result.internalRef	string	Internal reference number for intermediaries
result.branchCode	string	The branch code to which the KYC is attached
result.maritalStatus	string	The marital status of the user Married Unmarried Others
result.networth	string	The net worth of the user or the organization
result.networthDate	string	The net worth of the user or the organization as on date
result.incorpPLC	string	The place of incorporation of the organization, if applicable
result.otherInformation	string	Any additional information about the user or organization
result.remarks	string	The remarks associated with the application
result.accOpenDate	string	The date when account was opened
result.accActiveDate	string	The date when account was activated
result.accUpdateDate	string	The date when account was last updated
result.status	string	A code that represents the current status of the KYC application
result.statusDate	string	The date when the KYC application status was updated
result.errorDescription	string	The description of any errors encountered
result.dumpType	string	The type of data dump classification
result.dnlDdt	string	The date when data was downloaded
result.iopFlag	string	Indicates whether the KYC application is associated with CAMS or another KRA
result.kraInfo	string	The KRA information
result.signature	string	The Digital signature information
result.kycMode	string	The mode of KYC used for an application
result.uidToken	string	The unique identifier token
result.versionNo	string	The Version number of the application
result.fatcaApplicableFlag	string	The confirmation on whether the application is subject to FATCA regulations
result.fatcaBirthPlace	string	Place of birth for FATCA reporting
result.fatcaBirthCountry	string	The country of birth for FATCA reporting
result.fatcaCountryRes	string	The country of residence for FATCA reporting
result.fatcaCountryCityzenship	string	The country of citizenship for FATCA reporting
result.fatcaDateDeclaration	string	The date of FATCA declaration
result.type	string	Specifies whether the application is for an individual applicant or a non-individual applicant
result.resStatusProof	string	The address proof for a non-residential Indian or person of Indian origin. For the complete list of valid values for the parameter, please refer to this page
result.appResDate	string	The date and time when response was received
metaData	object	Metadata associated with the request
metaData.requestId	string	The unique identifier for the request
metaData.transactionId	string	The unique identifier for the transaction

Error Responses

The following are some error responses from the CAMS KRA Download API:

Invalid PAN Format

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

Invalid DOB Provided

{
    "status": "failure",
    "statusCode": "400",
    "result": {
        "message": "Invalid DOB provided"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Request Details

{
    "status": "failure",
    "statusCode": "400",
    "result": {
        "message": "Invalid request details"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Duplicate Request

{
    "status": "failure",
    "statusCode": "400",
    "result": {
        "message": "Duplicate request"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

{
    "status": "failure",
    "statusCode": 401,
    "result": {
        "message": "Missing/Invalid credentials"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Token Generation

{
    "status": "failure",
    "statusCode": 500,
    "result": {
        "message": "Invalid token generation"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Encrypted Data

{
    "status": "failure",
    "statusCode": 500,
    "result": {
        "message": "Invalid encrypted data"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid Batch Date And Time Format

{
    "status": "failure",
    "statusCode": "500",
    "result": {
        "message": "Invalid batch date and time format"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid User ID And Password

{
    "status": "failure",
    "statusCode": "500",
    "result": {
        "message": "Invalid user id and password"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Incorrect Total Records Count

{
    "status": "failure",
    "statusCode": "500",
    "result": {
        "message": "Incorrect Total records count"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid KRA Code

{
    "status": "failure",
    "statusCode": "500",
    "result": {
        "message": "Invalid KRA code"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error

{
    "status": "failure",
    "statusCode": "500",
    "result": {
        "message": "Internal Server Error"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response 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	Error Resolution
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)	Provide a valid PAN in the correct format
400	Invalid DOB provided	The date of birth provided is not valid	Provide a valid date of birth in DD-MM-YYYY format
400	Invalid request details	The request details provided are incomplete or incorrect	Verify and provide all required request parameters
400	Duplicate request	The request has already been submitted previously	Use a different transaction ID or wait before retrying
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
500	Invalid token generation	Creds Issue	Verify and provide valid credentials
500	Invalid encrypted data	Its due to invalid inputs	Verify and provide valid input data
500	Invalid batch date and time format	Due to invalid date format	Provide a valid date and time format
500	Invalid user id and password	Creds Issue	Verify and provide valid user ID and password
500	Incorrect Total records count	The total records count provided is incorrect	Verify and provide the correct total records count
500	Invalid KRA code	KRA code is invalid	Verify and provide a valid KRA code
500	Internal Server Error	An internal server error occurred	Please check the request headers or contact the HyperVerge team for resolution