CKYC Upload (Individuals)

post https://in.staging.decentro.tech/v2/kyc/ckyc/bulk/individuals/upload

🙌
Important Note
Please use only Staging Credentials on each API Reference page to test the APIs directly from our Documentation.

API Endpoints

Environment	Endpoint
Staging / Sandbox	https://in.staging.decentro.tech/v2/kyc/ckyc/bulk/individuals/upload
Production	https://in.decentro.tech/v2/kyc/ckyc/bulk/individuals/upload

This API reference details the interface for uploading individuals to the CKYC registry.

For a high level understanding of the API, refer to CKYC Bulk Upload Guide

`verifier` Object

The verifier object represents details of an employee from the regulated entity that has verified the records to be uploaded on CKYC registry.

The object is a mandatory field for all CKYC bulk uploads, and contains the parameters denoted in the table mentioned below.

Parameter	Type	Mandatory	Definition
`name`	String	Yes	The name of the employee who has done the KYC verification and is performing the CKYC upload.
`designation`	String	Yes	The designation of the employee who is performing the CKYC upload.
`kyc_declaration_place`	String	Yes	The place of declaration or verification of the KYC documents.
`employee_code`	String	Yes	The employee code of the person performing the CKYC upload.
`individuals`	Array	No	An array of individuals whose details are to be uploaded to CKYC. Refer the Individuals array
`legal_entities`	Array	No	An array of legal entities whose details are to be uploaded to CKYC.

`individuals` Array

The individuals array denotes a list of users who have to be either created or updated in the CKYC registry.

The details and validations of the objects inside the array are provided in the table mentioned below.

Parameter	Type	Mandatory	Definition
`identifier`	String	Yes	A unique reference ID of this user set by the RE. This is a mandatory field.
`salutation`	String	Yes	The salutation of the user should be less than 5 characters. Examples are "MR", "MRS", "MS" and "MX"
`name`	String	Yes	The full name of the user.
`gender`	String	Yes	The gender of the user can be one of the following: `MALE`, `FEMALE` and `TRANSGENDER`
`date_of_birth`	String	Yes	The date of the birth of the user. Validation is done on the format. The date format needs to be “YYYY-MM-DD”.
`relative`	Object	Yes	The object contains the type (string) and name (string) of the relative. The type of the relative can be one `FATHER` or `SPOUSE`
`location`	Object	Yes	The object that denotes the full address of the individual.
`document_submission_type`	String	Yes	String denoting the types of documents submitted. Please refer to the Document Submission Type section.
`documents`	Array	Yes	Array representing the list of documents. Following documents are mandatory: • 1 document of type `PHOTOGRAPH` • 1 valid document that can be a Proof of Address Refer to the Document Type section to learn more about the valid values for the type field in the members of documents array.
`ids`	Array	Yes`	Array representing the list of IDs collected for the user. • 1 document ID of type `PAN` is mandatory. • 1 valid document ID that can be a Proof of Address Refer to the ID type section to learn more about the valid values for the type field in the members of documents array.

`location` Object

Parameter	Type	Mandatory	Definition
`address`	String	Yes	The address string denoting the address of the user.
`pincode`	String	Yes	A pincode of the address of the user.
`state`	String	No	The state of the address of the user.
`city`	String	No	The city of the address of the user.

`relative` Object

Parameter	Type	Mandatory	Definition
`type`	String	Yes	The `type` of the relative mentioned for the user. The `type` can be one of the following: • `FATHER` • `SPOUSE`
`name`	String	Yes	The full name of the relative of the user.

`documents` Array

The documents array is a list of objects. The following table represents the member objects of the documents array.

Parameter	Type	Mandatory	Definition
`base64`	String	Yes	The `base64` string containing the actual image of the document. The maximum allowed size for these documents is 1 MB.
`type`	String	Yes	The `type` of the document for the user. The `type` can be one of the following: • `PASSPORT` • `VOTER_ID` • `PAN` • `DRIVING_LICENSE` • `AADHAAR` • `NREGA` • `EKYC` • `OFFLINE_AADHAAR` • `OTHERS`

`ids` Array

The ids array is a list of objects. The following table represents the member objects of the ids array.

Parameter	Type	Mandatory	Definition
`id_number`	String	Yes	The ID number corresponding to the ID `type`.
`type`	String	Yes	The `type` of the ID of the user. The `type` can be one of the following: • `PHOTOGRAPH` • `PASSPORT` • `VOTER_ID` • `PAN` • `DRIVING_LICENSE` • `AADHAAR` • `NREGA` • `SIGNATURE` • `EKYC` • `CKYC_ID` • `OTHERS`

👍
Skip CKYC Search Step by passing the CKYC_ID in the ids array. This will push the record directly to Update pipeline.

Response Keys

Here's a table of all CKYC Upload response keys and their descriptions:

Code	Description
error_invalid_relative_name	Error Invalid Relative Name Error
error_invalid_relative_type	Error Invalid Relative Type Error
error_empty_relative_type	Error Empty Relative Type Error
error_empty_relative_name	Error Empty Relative Name Error
error_empty_emp_code	Empty EMP Code Error
error_empty_branch	Empty Branch Error
error_invalid_id_number	Invalid ID Number Error
error_invalid_document_submission_type	Invalid Document Submission Type
error_invalid_pincode	Invalid Pincode Error
error_empty_date_of_birth	Empty Date Of Birth Error
error_invalid_name	Invalid Name Error
error_empty_name	Empty Name Error
error_empty_city	Empty City Error
error_invalid_gender	Invalid Gender Error
error_empty_verifier_name	Empty Verifier Name Error
error_invalid_city	Invalid City Error
error_empty_individuals	Empty Individuals Error
error_invalid_address	Invalid Address Error
error_empty_location	Empty Location Error
error_invalid_ids	Invalid IDs Error
error_empty_document_submission_type	Empty Document Submission Type
error_invalid_verifier_designation	Invalid Verifier Designation
error_empty_documents	Empty Documents Error
error_empty_identifier	Empty Identifier Error
error_empty_base64	Empty base64 Error
error_invalid_branch	Invalid Branch Error
error_invalid_date_of_birth	Invalid Date of Birth Error
error_invalid_verifier_name	Invalid Verifier Name Error
error_empty_salutation	Empty Salutation Error
error_empty_address	Empty Address Error
error_empty_verifier_designation	Empty Verifier Designation Error
error_invalid_document_type	Invalid Document Type Error
error_invalid_salutation	Invalid Salutation Error
error_invalid_individuals	Invalid Individuals Error
error_invalid_location	Invalid Location Error
error_invalid_batch_details	Invalid Batch Details Error
error_invalid_emp_code	Invalid EMP Code Error
error_empty_state_code	Empty State Code Error
error_empty_id_number	Empty ID Number Error
success_initiate_bulk_upload	Success Initiate Bulk Payload
error_empty_ids	Empty IDs Error
error_invalid_base64	Invalid Base64 Error
error_empty_document_type	Empty Document Type Error
error_empty_pincode	Empty Pincode Error
error_empty_batch_details	Empty Batch Details Error
error_empty_gender	Empty Gender Error
error_invalid_state_code	Invalid State Code Error
error_invalid_documents	Invalid Documents Error
error_invalid_identifier	Invalid Identifiers Error
error_invalid_payload	Invalid Payload Error
error_duplicate_identifier	Duplicate Identifier Error
error_empty_employee_code	Empty Employee Code Error
error_empty_verifier	Empty Verifier Error
error_invalid_kyc_declaration_place	Invalid KYC Verification Place Error
error_invalid_employee_code	Invalid Employee Code Error
error_empty_kyc_declaration_place	Empty KYC Declaration Place Error
error_invalid_verifier	Error Invalid Verifier
error_invalid_relative	Invalid Relative Error
error_empty_relative	Empty Relative Error
error_upload_limit_exceeded
success_bulk_upload_status_extracted	Success CKYC Upload Status Extracted
success_bulk_upload_entity_status_extracted	Success CKYC Upload Entity Status Extracted
error_empty_incorporation_date	Empty Incorporation Date Error
error_empty_related_individual_ckyc_id	Empty Related Individual CKYC ID Error
error_empty_entity_name	Empty Entity Name Error
error_empty_incorporation_country_code	Empty Incorporation Country Code Error
error_empty_related_individuals	Empty Related Individuals Error
error_invalid_related_individual_deletion_flag	Invalid Related Individual Deletion Flag Error
error_empty_incorporation_place	Empty Incorporation Place Error
error_invalid_related_individuals	Invalid Related Individuals
error_invalid_related_individual_ckyc_id	Invalid Related Individual CKYC ID Error
error_invalid_commencement_date	Invalid Commencement Date Error
error_invalid_related_individual_name	Invalid Related Individual Name Error
error_empty_commencement_date	Empty Commencement Date Error
error_invalid_incorporation	Invalid Incorporation Error
error_invalid_legal_entites	Invalid Legal Entities Error
error_invalid_incorporation_country_code	Invalid Incorporation Country Code Error
error_empty_related_individual_salutation	Empty Related Individual Salutation Error
error_empty_constitution_type	Empty Constitution Type Error
error_invalid_entity_name	Invalid Entity Name Error
error_empty_legal_entites	Empty Legal Entities Error
error_empty_related_individual_type	Empty Related Individual Type
error_invalid_constitution_type	Invalid Constitution Type Error
error_invalid_incorporation_date	Invalid Incorporation Date Error
error_empty_related_individual_deletion_flag	Empty Related Individual Deletion Flag Error
error_empty_incorporation	Empty Incorporation Error
error_empty_related_individual_name	Empty Related Individual Name Error
error_invalid_document_submission_type	Invalid Document Submission Type
error_invalid_document_type	Invalid Document Type Error

Callback Request Body Samples

Response Key	Example Callback
`BULK_CKYC_UPLOAD_RECORDS_PROCESSING_COMPLETED`	{ "attempt": 1, "referenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "bulkDecentroTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "callbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "originalCallbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2024-06-13T10:36:28.057662", "creationTimestamp": "2024-06-13T10:34:06.597703", "lastModificationTimestamp": "2024-06-13T10:36:28.039921", "type": "BULK_CKYC_INDIVIDUALS_UPLOAD", "stage": "BULK_CKYC_UPLOAD_RECORDS_PROCESSING_COMPLETED", "status": "PROCESSING", "description": "Records Processing Completed" }
`BULK_CKYC_UPLOAD_CSV_GENERATION_COMPLETED`	{ "attempt": 1, "referenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "bulkDecentroTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "callbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "originalCallbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2024-06-13T10:36:28.871262", "creationTimestamp": "2024-06-13T10:34:06.597703", "lastModificationTimestamp": "2024-06-13T10:36:28.856519", "type": "BULK_CKYC_INDIVIDUALS_UPLOAD", "stage": "BULK_CKYC_UPLOAD_CSV_GENERATION_COMPLETED", "status": "PROCESSING", "description": "CSV Generation Completed" }
`BULK_CKYC_UPLOAD_RECORDS_UPLOADING_COMPLETED`	{ "attempt": 1, "referenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "bulkDecentroTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "callbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "originalCallbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2024-06-13T10:36:32.604958", "creationTimestamp": "2024-06-13T10:34:06.597703", "lastModificationTimestamp": "2024-06-13T10:36:32.584826", "type": "BULK_CKYC_INDIVIDUALS_UPLOAD", "stage": "BULK_CKYC_UPLOAD_RECORDS_UPLOADING_COMPLETED", "status": "PROCESSING", "description": "Records Processing Completed" }
`BULK_CKYC_UPLOAD_REQUEST_ACKNOWLEDGED`	{ "attempt": 1, "referenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "bulkDecentroTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "callbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "originalCallbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2024-06-13T10:51:47.862506", "creationTimestamp": "2024-06-13T10:34:06.597703", "lastModificationTimestamp": "2024-06-13T10:51:13.415924", "type": "BULK_CKYC_INDIVIDUALS_UPLOAD", "stage": "BULK_CKYC_UPLOAD_REQUEST_ACKNOWLEDGED", "status": "PROCESSING", "description": "Upload request acknowledged by CERSAI", "data": { "uploadedFileName": "DUMMY_FILENAME.txt" }}
`BULK_CKYC_UPLOAD_RECORDS_UPLOAD_SUCCESSFUL`	{ "attempt": 1, "referenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "bulkDecentroTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "callbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "originalCallbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "timestamp": "2024-06-14T12:31:56.994998", "creationTimestamp": "2024-06-13T10:34:06.597703", "lastModificationTimestamp": "2024-06-14T12:31:56.971892", "type": "BULK_CKYC_INDIVIDUALS_UPLOAD", "stage": "BULK_CKYC_UPLOAD_RECORDS_UPLOAD_SUCCESSFUL", "status": "COMPLETED", "description": "Records Upload Success", "data": { "totalRecords": 93, "processedRecords": 93, "invalidRecords": 6, "approvedRecords": 75, "rejectedRecords": 12 } }

Unified Callback Structure

The v2 of CKYC Upload will send a unified callback that contains both the bulk response as well as individual line item responses. A sample of the callback structure is shown below:

{
    "referenceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "bulkDecentroTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "callbackTxnId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "timestamp": "2024-06-14T12:31:56.994998",
    "creationTimestamp": "2024-06-13T10:34:06.597703",
    "type": "BULK_CKYC_INDIVIDUALS_UPLOAD",
    "stage": "BULK_CKYC_UPLOAD_RECORDS_UPLOAD_SUCCESSFUL",
    "status": "COMPLETED",
    "description": "The CKYC records batch has been uploaded successfully.",
    "summary": {
        "totalRecords": 93,
        "processedRecords": 93,
        "invalidRecords": 6,
        "approvedRecords": 75,
        "rejectedRecords": 12
    },
    "data": {
        "identifier1": {
            "stage": "RECORD_UPLOAD_SUCCESSFUL",
            "status": "COMPLETED",
            "providerMessage": [
                {
                    "remarks": "Update request successfully approved by checker for the CKYC number 01234567891234. The Update reference number is 01234567891",
                    "description": "The update request has been approved and processed successfully. No further action required.",
                    "reupload": false
                }
            ],
            "additionalData": {
                "ckycReferenceId": "01234567891",
                "ckycId": "01234567891234"
            }
        },
        "identifier2": {
            "stage": "RECORD_UPLOAD_SUCCESSFUL",
            "status": "COMPLETED",
            "providerMessage": [
                {
                    "remarks": "Update request successfully approved by checker for the CKYC number 01234567891234. The Update reference number is 01234567891",
                    "description": "The update request has been approved and processed successfully. No further action required.",
                    "reupload": false
                }
            ],
            "additionalData": {
                "ckycReferenceId": "01234567891",
                "ckycId": "01234567891234"
            }
        },
        "identifier3": {
            "stage": "RECORD_UPLOAD_SUCCESSFUL",
            "status": "COMPLETED",
            "providerMessage": [
                {
                    "remarks": "Update request successfully approved by checker for the CKYC number 01234567891234. The Update reference number is 01234567891",
                    "description": "The update request has been approved and processed successfully. No further action required.",
                    "reupload": false
                }
            ],
            "additionalData": {
                "ckycReferenceId": "01234567891",
                "ckycId": "01234567891234"
            }
        }
    }
}

List of all responses

The line items in the unified callback will have the following remarks along with the corresponding descriptions and reupload. Also note, that each line item may also come with the additionalData object which can contain ckycReferenceId, ckycId or both.

Remark	Description	Recommend Reupload
Update request successfully approved by checker for the CKYC number XXXXXX. The Updated reference number is XXXXX.	The update request has been approved and processed successfully. No further action is required.	No
The last 4 digits of Aadhaar, Name, DOB, and Gender match with that of CKYC no XXXXX. Please download the record.	The provided Aadhaar details match an existing CKYC record. Download the existing CKYC record for further action. No reupload required unless changes are needed.	No
KYC Number is not linked	The KYC number provided has not been linked to the account. Link the KYC number to the account before proceeding. Reupload after downloading the record post user consent only.	No
Impermissible values entered in XXXXX	Invalid data or characters were entered in the specified field. Ensure valid values are entered. Reupload after correcting.	Yes
Number of Identity Details in 20 type does not match the count of 30 type records provided	The count of identity details provided does not match across fields. Correct the number of records in the respective fields so they match. Reupload after correcting.	Yes
Your request cannot be processed as there is another update request under process for this record.	Another update request for the same record is already being processed. Wait 24 hours, then submit a new request.	Yes
Please enter a valid Permanent State code, PIN is not matching with State	The provided PIN code does not match the entered State. Correct the PIN and State combination. Reupload after correcting.	Yes
Application Type should be 03 for update module	There was an error in segregating this record as an existing record, and hence was pushed to the creation pipeline. Please add the CKYC Number in the list of IDs and reupload.	Yes
FIELD_NAME update Flag should be entered	Indicates that a specific field's update flag is required. Ensure that the update flag for the specified field is properly entered. Reupload after correcting.	Yes
Please enter XXXXXXXXX Update Flag	An update flag for the field XXXXXX is required but not provided. Enter the update flag for the field XXXXXX. Reupload after correcting.	Yes
PAN number already exists in the system with KYC number XXXXXX. Please download the record.	The provided PAN is already linked to an existing KYC record with the KYC number XXXXXX. Download the existing KYC record for further actions. No reupload needed unless data needs updating.	No
Details inserted successfully for the Reference Number XXXXX	The data has been successfully submitted and processed. No further action required.	No
Please enter same ID number for E-KYC Authentication / Offline Verification / Proof of Possession of Aadhaar	The ID number provided for different verification steps must match. Verify and ensure the same ID is used for all verification steps. Reupload after correcting.	Yes
PAN number already exists with CKYC number CKYC_NUMBER	The provided PAN is already linked to another CKYC number CKYC_NUMBER. Use the existing CKYC number for future references or update requests.	No
This CKYC number is deactivated. Kindly use CKYC number XXXXXXXXXXX to fetch the KYC record.	The provided CKYC number is deactivated, and an alternative number XXXXXXX should be used to access the KYC record. Use the provided CKYC number to fetch the record. Reupload only if necessary.	No
The photograph image size should be less than 100 KB	The uploaded photograph exceeds the allowable file size limit. Compress the photograph to below 100 KB and reupload.	Yes
FIELD_NAME cannot start with a special character	This indicates that the input FIELD_NAME cannot begin with special characters. Please ensure input starts with an alphanumeric character. Reupload after correcting.	Yes
Please do not enter Images size more than 350 KB	The uploaded image exceeds the allowable file size limit. Compress the image to below 350 KB and reupload.	Yes
Applicant photo image cannot contain multiple pages	The uploaded image for the applicant’s photo must not span multiple pages or files. Reupload a single image file that does not contain multiple pages.	Yes
Application Type should be 01 for new upload	There was an error in segregating this record as a new record, and hence was pushed to the “Edit” pipeline. Please recheck all the details and reupload.	Yes
Cersai failed the record due to some unexpected reason.	The record failed to process due to a system error in CERSAI. Retry the process later. No immediate reupload necessary.	Yes
PAN number cannot be updated to FORM60	You cannot change a PAN number to FORM60. Provide the correct PAN number without switching to FORM60. Reupload after correcting.	Yes
Line number should be in sequence	The line number in the data should follow sequential order. Ensure all line numbers are in proper sequence. Reupload after correcting.	Yes
Please do not provide applicant age less than 18 years for normal accounts / Minor accounts should be updated.	The applicant’s age is under 18 for a normal account. It should be set to minor, or an OTP-based eKYC is required. Update the account type to minor or use an OTP-based eKYC method for applicants under 18.	No
At least one Relation detail of type 'Guardian of minor' is mandatory	A relation detail of type "Guardian of minor" is required for applicants under 18 years of age. Provide the required relation details. Reupload after correcting.	Yes
Date of Birth Should not be a future date	The applicant's date of birth is in the future, which is invalid. Enter a valid date of birth that is not in the future. Reupload after correcting.	Yes
Please enter valid Constitution type in detail 20	An invalid Constitution type has been entered. Ensure a valid Constitution type is provided. Reupload after correcting.	Yes
Your request could not be processed due to some technical issues. Please try after some time.	The request failed due to technical errors in the system. Wait and retry the process after some time.	Yes

CKYC Upload (Individuals)

🙌
Important Note

API Endpoints

`verifier` Object

`individuals` Array

`location` Object

`relative` Object

`documents` Array

`ids` Array

👍
Skip CKYC Search Step by passing the `CKYC_ID` in the `ids` array. This will push the record directly to Update pipeline.

Response Keys

Callback Request Body Samples

Unified Callback Structure

List of all responses

🙌Important Note

API Endpoints

verifier Object

individuals Array

location Object

relative Object

documents Array

ids Array

👍Skip CKYC Search Step by passing the CKYC_ID in the ids array. This will push the record directly to Update pipeline.

Response Keys

Callback Request Body Samples

Unified Callback Structure

List of all responses

🙌
Important Note

`verifier` Object

`individuals` Array

`location` Object

`relative` Object

`documents` Array

`ids` Array

👍
Skip CKYC Search Step by passing the `CKYC_ID` in the `ids` array. This will push the record directly to Update pipeline.