Skip to main content

CKYC Upload API

This document highlights the CKYC Upload API details.

API Description​

Objective​

The CKYC Upload API submits the Know Your Customer (KYC) details of a user to the Central KYC Registry.

API URL​

https://ind-ckyc.hyperverge.co/api/v1/customer/upload

API Endpoint​

upload

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 or PUT​

Headers​

ParameterMandatory or OptionalDescriptionValid Values
content-typeMandatoryThis parameter defines the media type for the request payload.application/json
appIdMandatoryApplication ID shared by HyperVergeN/A. This is a unique value.
appKeyMandatoryApplication Key shared by HyperVergeN/A. This is a unique value.
transactionIdMandatoryUnique ID for the customer journey.N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs​

The mandatory fields required for the API are listed here. The following table provides the details of the parameter required for the API.

ParameterDescriptionMandatory or OptionalValid ValuesDefault Value
[Parameter]
info
The form data parameters such as photo, aadhaarFront, aadhaarBack, idFront and idBack, etc are described here.

The image of the officially valid document(OVD) that you are uploading to the central KYC register for the individual or the legal entity.
Caution
  • You should chose the Identity document parameter, according to your requirement. A comprehensive list for such documents and their categories is provided in the Valid Values section of this table
  • If uploading the details of a related person is required for the user, there should be two parameters corresponding to the user's OVD and the related person's OVD.
OptionalThe ID document selections for your image verification requirements are in the following two sections of the CKYC Upload - Reference Document page:

Not Applicable
metaDataThe user information that you are uploading to the Central KYC Registry. The payload inside this metadata parameter will be in JSON format. The sample input is shown in the following section. Mandatory The sample metadata is provided here for your referenceNot Applicable

Request​

The CKYC Upload API request body is structured into two categories based on the entity type: Individual, Legal Entity or Related Person.

  • Individual: This is for personal accounts where a single individual is the account holder.
  • Legal entity: This category is for organizations such as companies, partnerships, trusts, HUFs (Hindu Undivided Family), societies, and other non-individual entities.
  • Individual with related person: This category applies when an individual's KYC needs to account for another related person, often for reasons such as guardianship, joint accounts, or power of attorney arrangements.
curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/customer/upload' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'metadata="{}"' \  
// the fields below are optional
--form 'photo=@"<path_to_photo>"' \
--form 'aadhaarFront=@"<path_to_aadhaar_front>"' \
--form 'aadhaarBack=@"<path_to_aadhaar_back>"' \
--form 'idFront=@"<path_to_front_side_of_ID>"' \
--form 'idBack=@"<path_to_back_side_of_ID>"' \
--form 'passportFront=@"<path_to_passport_front>"' \
--form 'passportBack=@"<path_to_passport_back>"' \
--form 'dlFront=@"<path_to_driving_license_front>"' \
--form 'dlBack=@"<path_to_driving_license_back>"' \
--form 'voterIdFront=@"<path_to_voter_id_front>"' \
--form 'voterIdBack=@"<path_to_voter_id_back>"' \
--form 'voteridFront=@"<path_to_voterid_front>"' \
--form 'voteridBack=@"<path_to_voterid_back>"' \
--form 'jobCard=@"<path_to_job_card>"' \
--form 'signature=@"<path_to_signature>"' \
--form 'nationalPopRegLetter=@"<path_to_national_pop_reg_letter>"' \
--form 'ekycAuth=@"<path_to_ekyc_auth>"' \
--form 'aadhaarOffline=@"<path_to_aadhaar_offline>"'

Metadata​

This section elaborates on all the different form data fields that can be entered within the metaData form parameter. It provides sample code snippets showing the structure and parameters for each KYC metadata category - Individual, Legal Entity or Related Person:

The following metadata structure is used for individual personal accounts (single account holder):

{
  "constitutionType": "01",
  "isDifferentlyAbled": "yes", // new parameter
  "percentageOfImpairment": 20, // mandatory if isDifferentlyAbled is yes
  "typeOfImpairment": 1,        // mandatory if isDifferentlyAbled is yes
  "udidNumber": "<Enter_the_udid_number>", // mandatory if isDifferentlyAbled is yes
  "residentialStatus": "<Enter_the_residential_status>", // new parameter
  "branchCode": "<Enter_the_branch_code>",
  "accountType": "01",
  "applicantNamePrefix": "<Enter_the_applicant_name_prefix>",
  "applicantFirstName": "<Enter_the_applicant_first_name>",
  "applicantMiddleName": "<Enter_the_applicant_middle_name>",
  "applicantLastName": "<Enter_the_applicant_last_name>",
  "applicantMaidenNamePrefix": "<Enter_the_applicant_maiden_name_prefix>",
  "applicantMaidenFirstName": "<Enter_the_applicant_maiden_first_name>",
  "applicantMaidenMiddleName": "<Enter_the_applicant_maiden_middle_name>",
  "applicantMaidenLastName": "<Enter_the_applicant_maiden_last_name>",
  "fatherNamePrefix": "<Enter_the_father_name_prefix>",
  "fatherFirstName": "<Enter_the_father_first_name>",
  "fatherMiddleName": "<Enter_the_father_middle_name>",
  "fatherLastName": "<Enter_the_father_last_name>",
  "spouseNamePrefix": "<Enter_the_spouse_name_prefix>",
  "spouseFirstName": "<Enter_the_spouse_first_name>",
  "spouseMiddleName": "<Enter_the_spouse_middle_name>",
  "spouseLastName": "<Enter_the_spouse_last_name>",
  "motherNamePrefix": "<Enter_the_mother_name_prefix>",
  "motherFirstName": "<Enter_the_mother_first_name>",
  "motherMiddleName": "<Enter_the_mother_middle_name>",
  "motherLastName": "<Enter_the_mother_last_name>",
  "gender": "<Enter_the_gender>",
  "dob": "<Enter_the_dob>",
  "pan": "<Enter_the_pan>"/ "<FORM60>", // pass form 60 if PAN unavailable 
  "permanentCurrentAddressMatch": "Y",
  "address": {
    "line1": "<Enter_the_address_line1>",
    "line2": "<Enter_the_address_line2>",
    "line3": "<Enter_the_address_line3>",
    "city": "<Enter_the_city>",
    "district": "<Enter_the_district>",
    "state": "<Enter_the_state>",
    "country": "<Enter_the_country>",
    "pincode": "<Enter_the_pincode>",
    "proof": "<Enter_the_proof>"
  },
  "currentAddress": {
    "line1": "<Enter_the_current_address_line1>",
    "line2": "<Enter_the_current_address_line2>",
    "line3": "<Enter_the_current_address_line3>",
    "city": "<Enter_the_current_city>",
    "district": "<Enter_the_current_district>",
    "state": "<Enter_the_current_state>",
    "country": "<Enter_the_current_country>",
    "pincode": "<Enter_the_current_pincode>",
    "proof": "<Enter_the_current_proof>"
  },
  "contact": {
    "residenceTelephoneStdCode": "<Enter_the_residence_telephone_std_code>",
    "residenceTelephone": "<Enter_the_residence_telephone>",
    "officeTelephoneStdCode": "<Enter_the_office_telephone_std_code>",
    "officeTelephone": "<Enter_the_office_telephone>",
    "mobileIsdCode": "<Enter_the_mobile_isd_code>",
    "mobile": "<Enter_the_mobile>",
    "email": "<Enter_the_email>"
  },
  "idDetails": [
    {
      "type": "<Enter_the_id_type>",
      "number": "<Enter_the_id_number>"
    }
  ],
  "dateOfDeclaration": "<Enter_the_date_of_declaration>",
  "placeOfDeclaration": "<Enter_the_place_of_declaration>",
  "dateOfKYCVerification": "<Enter_the_date_of_kyc_verification>",
  "typeOfDocumentSubmitted": "<Enter_the_type_of_document_submitted>",
  "kycVerificationName": "<Enter_the_kyc_verification_name>",
  "kycVerificationDesignation": "<Enter_the_kyc_verification_designation>",
  "kycVerificationBranch": "<Enter_the_kyc_verification_branch>",
  "kycVerificationEmpCode": "<Enter_the_kyc_verification_emp_code>"
}

metaData Parameter Descriptions​

Parameter NameMandatory/OptionalAllowed Values and TypeParameter Description
constitutionTypeMandatoryString. Should not be null, undefined, or empty.Type of entity constitution. The possible values of constitutionType are provided here
isDifferentlyAbledMandatoryString. Should not be null or undefined. Must be one of the following values: yes, noIndicates if the person is differently abled
percentageOfImpairmentMandatory if isDifferentlyAbled is yesNumber. Should not be null or undefined. Must be between 1 and 100Percentage of impairment for differently abled persons
typeOfImpairmentMandatory if isDifferentlyAbled is yesNumber. Should not be null or undefined. Must be a valid impairment type codeType of impairment for differently abled persons. A list of impairment type codes is provided here.
udidNumberMandatory if isDifferentlyAbled is yesString. First 2 digit to be Alphabets and remaining 16 digits to be numeric. Should not be null or undefined. Must be of length 18Unique Disability ID number
residentialStatusMandatoryString. Should not be null or undefined. Must be one of the following values: resident, non-residentResidential status of the applicant
branchCodeMandatoryString. Should not be empty. Must be of length between 1 to 15Branch code of the financial institution
accountTypeMandatoryString. Should not be null or undefined. Must be of length 2. Must be one of the following values: 01,04,05Type of account.
  • 01: Normal
  • 04: OTP Based E-KYC
  • 05: Minor
applicantNamePrefixMandatoryString. Should not be null or undefined. Must be in between 1 to 5Prefix for applicant's name (Mr., Mrs., Dr., etc.)
applicantFirstNameMandatoryString. Should not be null or undefined. Must be in between 1 to 50First name of the applicant
applicantMiddleNameOptionalString. Should not be null or undefined. Must be in between 1 to 50Middle name of the applicant
applicantLastNameOptionalString. Should not be null or undefined. Must be in between 1 to 50Last name of the applicant
applicantMaidenNamePrefixOptionalString. Should not be null or undefined. Must be in between 1 to 5Prefix for applicant's maiden name
applicantMaidenFirstNameOptionalString. Should not be null or undefined. Must be in between 1 to 50First name of applicant's maiden name
applicantMaidenMiddleNameOptionalString. Should not be null or undefined. Must be in between 1 to 50Middle name of applicant's maiden name
applicantMaidenLastNameOptionalString. Should not be null or undefined. Must be in between 1 to 50Last name of applicant's maiden name
fatherNamePrefixConditionalString. Should not be null or undefined. Must be in between 1 to 5. Required if father details are providedPrefix for father's name. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
fatherFirstNameConditionalString. Should not be null or undefined. Required if father details are providedFirst name of father. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
fatherMiddleNameConditionalString. Should not be null or undefined. Required if father details are providedMiddle name of father. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
fatherLastNameConditionalString. Should not be null or undefined. Required if father details are providedLast name of father. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
spouseNamePrefixConditionalString. Should not be null or undefined. Must be in between 1 to 5. Required if spouse details are providedPrefix for spouse's name. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
spouseFirstNameConditionalString. Should not be null or undefined. Required if spouse details are providedFirst name of spouse. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
spouseMiddleNameConditionalString. Should not be null or undefined. Required if spouse details are providedMiddle name of spouse. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
spouseLastNameConditionalString. Should not be null or undefined. Required if spouse details are providedLast name of spouse. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
motherNamePrefixConditionalString. Should not be null or undefined. Must be in between 1 to 5. Required if mother details are providedPrefix for mother's name. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
motherFirstNameConditionalString. Should not be null or undefined. Required if mother details are providedFirst name of mother. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
motherMiddleNameConditionalString. Should not be null or undefined. Required if mother details are providedMiddle name of mother. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
motherLastNameConditionalString. Should not be null or undefined. Required if mother details are providedLast name of mother. Any one of the details - mother's name/ father's name /spouse's name field to be mandatorily provided
genderMandatoryString. Should not be null, undefined, or empty. Must be one of the following values: M,F,TGender of the applicant
dobMandatoryString. Should not be null, undefined, or empty. Must be of length 10. Should be in DD-MM-YYYY format or valid dateDate of birth of the applicant
panMandatoryString. Should not be null, undefined, or empty. Pan no should be valid. Must be of length less than 10Permanent Account Number of the applicant
permanentCurrentAddressMatchMandatoryString. Should not be null or undefined. Must be one of the following values: Y, N, TIndicates if permanent and current addresses match
dateOfDeclarationMandatoryString. Should not be null, undefined, or empty. Must be of length 10. Should be in DD-MM-YYYY format or valid dateDate of declaration by the applicant
placeOfDeclarationMandatoryString. Should not be null, undefined, or empty. Must be of length between 1 to 50Place where the declaration was made
dateOfKYCVerificationMandatoryString. Should not be null, undefined, or empty. Must be of length 10. Should be in DD-MM-YYYY format or valid dateDate when KYC verification was performed
typeOfDocumentSubmittedMandatoryString. Should not be null or undefined. Must be of length 2. Must be one of the following values: 01,02,03,04,05Type of document submitted for verification
kycVerificationNameMandatoryString. Should not be null or undefined. Must be in between 1 to 50Name of the person who performed KYC verification
kycVerificationDesignationMandatoryString. Should not be null or undefined. Must be in between 1 to 50Designation of the person who performed KYC verification
kycVerificationBranchMandatoryString. Should not be null or undefined. Must be in between 1 to 50Branch where KYC verification was performed
kycVerificationEmpCodeMandatoryString. Should not be null or undefined. Must be in between 1 to 50Employee code of the person who performed KYC verification
remarksOptionalNot ApplicableNot Applicable
addressMandatoryObject. Total length of address cannot exceed length 165Address information of the applicant
address.line1MandatoryStringFirst line of address
address.line2OptionalStringSecond line of address
address.line3OptionalStringThird line of address
address.cityMandatoryString. Should not be null or undefined. Must be in between 1 to 50City name
address.districtMandatory for India, Optional for other countriesString. Should not be null or undefined. Must be in between 1 to 50District name
address.stateMandatoryString. Should not be null or undefined. Must be of length 2State code
address.countryMandatoryString. Should not be null or undefined. Must be of length 2. Must be a valid 2-character ISO country code (e.g., IN for India, US for United States) The Country codes. A list of valid country codes is provided here.
address.pincodeMandatoryString. Should not be null or undefined. Pincode currently not supportedPostal code
address.proofMandatoryString. Should not be null or undefinedType of address proof document. A list of valid address proof documents is provided here.
currentAddressMandatory only if permanentCurrentAddressMatch = NNot ApplicableNot Applicable
currentAddress.line1MandatoryNot ApplicableNot Applicable
currentAddress.line2OptionalNot ApplicableNot Applicable
currentAddress.line3OptionalNot ApplicableNot Applicable
currentAddress.cityMandatoryNot ApplicableNot Applicable
currentAddress.districtMandatory for India, Optional for other countriesNot ApplicableNot Applicable
currentAddress.stateOptionalNot ApplicableNot Applicable
currentAddress.countryMandatoryNot ApplicableNot Applicable
currentAddress.pincodeMandatoryNot ApplicableNot Applicable
currentAddress.proofMandatoryNot Applicable cakeNot Applicable
contactOptionalNot ApplicableNot Applicable
contact.residenceTelephoneStdCodeOptionalString. Must be between length 1 to 4Standard code for residence telephone
contact.residenceTelephoneOptionalString. Must be of length 10Residence telephone number
contact.officeTelephoneStdCodeOptionalString. Must be between length 1 to 4Standard code for office telephone
contact.officeTelephoneOptionalString. Must be of length 10Office telephone number
contact.mobileIsdCodeOptionalString. Must be between length 1 to 3ISD code for mobile number
contact.mobileOptionalString. Must be of length 10Mobile number
contact.emailOptionalString. Must be of length between 1 to 100Email address
contact.faxStdCodeOptionalString. Should not be null or undefined. Must be between length 1 to 4Standard code for fax number
contact.faxOptionalString. Should not be null or undefined. Must be of length 10Fax number
constitutionTypeOthersMandatoryString. Should not be null or undefined. Must be of length 20Other constitution type details
entityNameMandatoryString. Should not be null or undefined. Must be in between 1 to 150Name of the legal entity
doiMandatoryString. Should not be null or undefined. Must be of length 10Date of incorporation
placeOfIncorporationMandatoryString. Should not be null or undefined. Must be of length between 1 to 50Place of incorporation
docMandatoryString. Should not be null or undefined. Must be of length 10Date of commencement
countryOfIncorporationMandatoryString. Should not be null or undefined. Must be of length 2Country of incorporation
tinOptionalString. Should not be null or undefined. Must be of length 20Tax Identification Number
tinIssueCountryOptionalString. Should not be null or undefined. Must be of length 2Country that issued the TIN
address.proofOfAddressLegalMandatoryString. Should not be null or undefined. Must be between length 1 and 75Proof of address for legal entity
idDetailsMandatoryArray. Values in idDetails should not be empty. idDetails[index].type should not be null or undefinedIdentity document details
idDetails[index].typeMandatoryStringType of identity document. A list of valid ID proof documents is provided here.
idDetails Mandatory StringDetails of the officially valid document (OVD) used for identification. The possible values of idDetails are provided here.
proofMandatory StringProof of identity or address document provided.The possible values of proof are provided here.

Success Response​

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "transactionid": "<Transaction_ID>",
    "message": "Request for upload has been successfully registered"
  }
}

Error Responses​

The following are some error responses from the CKYC Upload API:

The following is a sample error response you may receive when one or more required parameters are missing from the CKYC Upload API request body:

{
    "status": "failure",
    "statusCode": "400",
    "error": {
        "code": "ER_REQ_VALIDATE",
        "message": "user photo not found for related person"
    }
}
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: