CKYC Legal Update

Endpoint Overview

POST /api/v1/ckyc-upload/legal/update

Description

Updates existing legal entity CKYC records in the central registry via SFTP. The request structure mirrors the Legal Upload endpoint but targets records that already exist in the CKYC registry. Returns a client_id for tracking the async processing.

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Environment URLs:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token (`Bearer YOUR_JWT_TOKEN`)
Content-Type	Yes	`application/json`

Request Body

The request body is identical to the Legal Upload endpoint. Key fields:

Parameter	Type	Required	Description
data	Object	Yes	Root request payload
data.purpose	String	Yes	Purpose of the CKYC update
data.verifier	Object	Yes	Verification officer details (name, designation, branch, employment_code, organization)
data.legal_entities	Array	Yes	Array of legal entity records to update
data.legal_entities[].entity_name	String	Yes	Full legal name
data.legal_entities[].pan	String	Yes	PAN number
data.legal_entities[].constitution_type	String	Yes	Legal constitution type
data.legal_entities[].date_of_incorporation	String	Yes	`YYYY-MM-DD` format
data.legal_entities[].registered_address	Object	Yes	Registered office address
data.legal_entities[].related_persons	Array	Yes	Directors, signatories, beneficial owners
data.legal_entities[].identity_documents	Array	Yes	Entity identity documents
data.legal_entities[].images	Array	No	Base64-encoded document images

See Legal Upload for the complete field reference and example request.

Example Request

{
    "data": {
        "purpose": "Annual KYC update",
        "verifier": {
            "name": "Amit Shroff",
            "declaration_place": "Mumbai",
            "designation": "Compliance Officer",
            "branch": "Head Office",
            "employment_code": "EMP001",
            "organization_name": "Finkurve Financial Services Limited",
            "organization_code": "IN7196"
        },
        "legal_entities": [
            {
                "entity_name": "ABC PRIVATE LIMITED",
                "pan": "ABCDE1234F",
                "constitution_type": "PRIVATE_LIMITED",
                "date_of_incorporation": "2019-05-10",
                "place_of_incorporation": "NORTH DELHI",
                "country_of_incorporation": "IN",
                "tin_gst": "07ABCDE1234F1Z5",
                "registered_address": {
                    "address": "456 New Business Park, Sector 10",
                    "city": "New Delhi",
                    "district": "South Delhi",
                    "state_code": "DL",
                    "pincode": "110020",
                    "country_code": "IN"
                },
                "same_address": true,
                "related_persons": [
                    {
                        "prefix": "MR",
                        "first_name": "Vineet",
                        "last_name": "Kapoor",
                        "din": "1234567",
                        "dob": "1996-02-29",
                        "gender": "MALE",
                        "relationship_type": "DIRECTOR"
                    }
                ],
                "identity_documents": [
                    {
                        "id_number": "U72900DL2019PTC349962",
                        "type": "CERTIFICATE_OF_INCORPORATION"
                    }
                ]
            }
        ]
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Response payload
data.client_id	String	Unique identifier for tracking this update request
data.message	String	Status message
data.state	String	Initial state (`pending`)
data.error	Array	Validation errors, if any
status_code	Integer	HTTP status code
success	Boolean	Whether the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Example Successful Response

{
    "data": {
        "client_id": "ckyc_legal_update_xYzAbCdEfGhIjKlMnOpQ",
        "message": "CKYC bulk upload has been initiated",
        "state": "pending",
        "error": []
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Failed

Not Registered

Validation Error

{
    "data": null,
    "status_code": 401,
    "success": false,
    "message": "Authentication failed",
    "message_code": "unauthorized"
}

:::caution Heads Up!

Update vs Upload -- This endpoint updates existing records. To register new entities, use Legal Upload.

Permission -- Requires ckyc-legal-upload.

Billing -- Billed per legal entity record (ckyc_legal_update).

180-day TTL -- Update records are automatically deleted after 6 months.

State machine -- See the parent index for full state and sub-state reference.
:::

Code Samples

cURL

Python

Node.js

Next Steps

Legal Upload Status -- Poll the processing status using your client_id

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ckyc-upload/legal/update' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "data": { "purpose": "Annual KYC update", "verifier": { "name": "Amit Shroff", "declaration_place": "Mumbai", "designation": "Compliance Officer", "branch": "Head Office", "employment_code": "EMP001", "organization_name": "Finkurve Financial Services Limited", "organization_code": "IN7196" }, "legal_entities": [ { "entity_name": "ABC PRIVATE LIMITED", "pan": "ABCDE1234F", "constitution_type": "PRIVATE_LIMITED", "date_of_incorporation": "2019-05-10", "place_of_incorporation": "NORTH DELHI", "country_of_incorporation": "IN", "tin_gst": "07ABCDE1234F1Z5", "registered_address": { "address": "456 New Business Park, Sector 10", "city": "New Delhi", "district": "South Delhi", "state_code": "DL", "pincode": "110020", "country_code": "IN" }, "same_address": true, "related_persons": [ { "prefix": "MR", "first_name": "Vineet", "last_name": "Kapoor", "din": "1234567", "dob": "1996-02-29", "gender": "MALE", "relationship_type": "DIRECTOR" } ], "identity_documents": [ { "id_number": "U72900DL2019PTC349962", "type": "CERTIFICATE_OF_INCORPORATION" } ] } ] } }'

{ "data": { "client_id": "ckyc_legal_update_xYzAbCdEfGhIjKlMnOpQ", "message": "CKYC bulk upload has been initiated", "state": "pending", "error": [] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

CKYC Legal Update

CKYC Legal Update#

Description#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Code Samples#

Request

Responses

CKYC Legal Update

Description

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Code Samples