CKYC Bulk Upload

πŸ’« πŸ§™β€β™‚οΈ One API to create them all, one API to find them. One API to bring them all, and in the registry bind them.

Decentro's CKYC Bulk Upload product is an abstraction over CKYC's SFTP Upload via a simple API. The solution lets customers seamlessly push bulk users and their documents via a single API hit.

Decentro will perform all the validations, image processing, image compression, batch building, connecting to the Financial Institution's SFTP server and uploading the users to CKYC in the format recommended by them.

CKYC Bulk Upload

CKYC Bulk Upload

Additionally, Decentro will also parse all stage-wise and periodic response files from CKYC. We will send you an email whenever an upload is pending on the CKYC portal, and also send detailed reports about approved and rejected updates from CKYC.

Lastly, to add more touch points to the entire flow described above, Decentro's CKYC Bulk Upload solution also comes with status check APIs, both at the transaction level as well as the unit entity level (whether it's a batch of individuals or legal entities).

In short, you get to combine the best of both worlds, with the simplicity of an API interface and the stability of SFTP connection. Decentro handles the SFTP connection in the backend so that you don't have to worry about pushing and polling files from SFTP, and does all the heavy-lifting required to parse the API request payload into CKYC's format.

This documentation highlights the high-level interface and integration requirements using which a RE (regulated entity) can upload 1 or more individual users or legal entities to the CKYC Record Registry.

For a more granular understanding of the CKYC Bulk Upload solution, please refer to the CKYC Bulk Upload API for individuals and legal entities.

πŸ“‘ Request Contract

The request contract for CKYC bulk upload will have the following parameters:

ParameterTypeMandatoryDefinition
reference_idStringYesA unique reference ID of this transaction set by the RE (UUID recommended)
consentBooleanYesA mandatory field for compliance. This field accepts a boolean value and must be true for the transaction to go through.
purposeStringYesThe purpose of this transaction
verifierObjectYesThis is an object that contains the KYC verifier details. Please refer to the Verifier section to learn more about the parameters within this object.
individualsArrayNoAn array of individuals whose details are to be uploaded to CKYC. Refer the Individuals array
legal_entitiesArrayNoAn array of legal entities whose details are to be uploaded to CKYC.

πŸ‘

Rule of Thumb

You must either send a list of individuals or a list of legal_entities only.

You cannot send both these fields in the same request because CKYC has different rules for creating a batch of different entities and mandates that a batch has either only a set of individuals or legal_entities.

Hence, to maintain simplicity and a clean interface, we have segregated CKYC Upload for Individuals and Legal Entities into 2 separate APIs.

πŸ§‘πŸ» Upload Individuals

The following shows a sample request and response body for upload individuals to the CKYC Record Registry. For more information on the parameters inside the individuals array, please refer to the Upload Individuals API for individuals.

{
    "reference_id": "12345",
    "consent": true,
    "purpose": "For bank account purpose",
    "verifier": {
        "name": "John Doe",
        "designation": "CEO",
        "employee_code": "123456789",
        "kyc_declaration_place": "Bangalore"
    },
    "individuals": [
        {
            "identifier": "1",
            "salutation": "MR",
            "name": "John Doe",
            "gender": "MALE",
            "date_of_birth": "YYYY-MM-DD",
            "location": {
                "address": "XXXXXXXXXXXXXXXXXXXX",
                "pincode": "XXXXXX"
            },
            "document_submission_type": "EKYC",
            "relative": {
                "salutation": "MR",
                "type": "FATHER",
                "name": "John Doe"
            },
            "documents": [
                {
                    "base64": "xxxx",
                    "type": "AADHAAR"
                },
                {
                    "base64": "xxxx",
                    "type": "PHOTOGRAPH"
                }
            ],
            "ids": [
                {
                    "id_number": "ABCDE1234F",
                    "type": "PAN"
                },
                {
                    "id_number": "XXXXXXXX1234",
                    "type": "VOTER_ID"
                }
            ]
        }
    ]
}
{
    "decentroTxnId": "DEC001",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "CKYC bulk upload has been initiated",
    "responseKey": "success_initiate_bulk_upload"
}

🏦 Upload Legal Entities

The following shows a sample request and response body for upload legal entities to the CKYC Record Registry.

{
    "reference_id": "12345",
    "consent": true,
    "purpose": "For bank account purpose",
    "verifier": {
        "name": "John Doe",
        "designation": "CEO",
        "employee_code": "123456789",
        "kyc_declaration_place": "Bangalore"
    },
    "legal_entities": [
        {
            "identifier": "1",
            "consitution_type": "PARTNERSHIP_FIRM",
            "entity_name": "John Doe Partners",
            "incorporation": {
	            "place": "Bangalore",
	            "date": "YYYY-MM-DD",
	            "country": "XXXXX"
            },
            "commencement_date": "YYYY-MM-DD",
            "location": {
                "address": "XXXXXXXXXXXXXXX",
                "pincode": "XXXXXX"
            },
            "document_submission_type": "CERTIFIED_COPIES",
            "documents": [
                {
                    "base64": "<base64>",
                    "type": "OFFICIALLY_VALID_DOCUMENT"
                },
                {
                    "base64": "<base64>",
                    "type": "CERTIFICATE_OF_INCORPORATION"
                }
            ],
            "ids": [
                {
                    "id_number": "ABCDE1234F",
                    "type": "OFFICIALLY_VALID_DOCUMENT"
                },
                {
                    "id_number": "XXXXXXXX1234",
                    "type": "CERTIFICATE_OF_INCORPORATION"
                },
                {
                    "id_number": "ABCDE1234F",
                    "type": "GSTIN"
                },
                {
                    "id_number": "XXXXXXXX1234",
                    "type": "PAN"
                }
            ]
        }
    ] 
}
{
    "decentroTxnId": "DEC001",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "message": "CKYC bulk upload has been initiated",
    "responseKey": "success_initiate_bulk_upload"
}

⚑️Status Updates

Both Individuals and legal entities similar GTS APIs and the response contracts are mentioned below.

πŸ“š Bulk Transaction GTS

{
    "decentroTxnId": "XXXXXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "data": {
        "referenceId": "XXXXXX",
        "bulkDecentroTxnId": "XXXXXX",
        "individuals": {
            "requested": 10,
            "processed": 1,
            "successful": 9,
            "failed": 1,
            "pending": 0,
            "failedIdentifiers": [
                "123456789"
            ]
        },
        "stage": "BULK_CKYC_UPLOAD_RECORDS_UPLOADING_SUCCESSFUL",
        "status": "SUCCESS",
        "description": "Records Uploading Succeeded",
        "creationTimestamp": "XXXXXXXXX",
        "lastModificationTimestamp": "XXXXXXXXX"
    },
    "responseKey": "success_bulk_upload_status_extracted"
}

πŸ“— Unit Entity GTS

{
    "decentroTxnId": "XXXXXXXX",
    "status": "SUCCESS",
    "responseCode": "S00000",
    "data": {
        "identifier": "123456789",
        "referenceId": "XXXXXX",
        "bulkDecentroTxnId": "XXXXXXXX",
        "stage": "RECORD_VALIDATION_COMPLETED",
        "remarks": "Accepted by CKYC Registry",
        "status": "PROCESSING",
        "description": "Record Validation Completed",
        "creationTimestamp": "XXXXXXXXXX",
        "lastModificationTimestamp": "XXXXXXXXXX"
    },
    "responseKey": "success_bulk_upload_entity_status_extracted"
}