CKYC Legal Upload

Endpoint Overview

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

Description

Registers new legal entity CKYC records in the central registry via SFTP. Submit one or more legal entities with entity details, related persons (directors, signatories, beneficial owners), identity documents, addresses, and verifier information. 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

Parameter	Type	Required	Description
data	Object	Yes	Root request payload
data.purpose	String	Yes	Purpose of the CKYC upload
data.verifier	Object	Yes	Verification officer details
data.verifier.name	String	Yes	Full name of the verifier
data.verifier.declaration_place	String	Yes	Place of declaration
data.verifier.designation	String	Yes	Designation of the verifier
data.verifier.branch	String	Yes	Branch name
data.verifier.employment_code	String	Yes	Employee code
data.verifier.organization_name	String	Yes	Organization name
data.verifier.organization_code	String	Yes	Organization code (FI code)
data.legal_entities	Array	Yes	Array of legal entity records
data.legal_entities[].entity_name	String	Yes	Full legal name of the entity
data.legal_entities[].pan	String	Yes	PAN number of the entity
data.legal_entities[].constitution_type	String	Yes	Type of legal constitution (e.g., `PRIVATE_LIMITED`, `PUBLIC_LIMITED`, `LLP`, `PARTNERSHIP`, `TRUST`, `SOCIETY`, `HUF`)
data.legal_entities[].date_of_incorporation	String	Yes	Date of incorporation (`YYYY-MM-DD`)
data.legal_entities[].place_of_incorporation	String	No	Place of incorporation
data.legal_entities[].country_of_incorporation	String	No	Country code (e.g., `IN`)
data.legal_entities[].tin_gst	String	No	TIN or GST registration number
data.legal_entities[].date_of_commencement	String	No	Date business commenced (`YYYY-MM-DD`)
data.legal_entities[].registered_address	Object	Yes	Registered office address
data.legal_entities[].registered_address.address	String	Yes	Complete address line
data.legal_entities[].registered_address.city	String	Yes	City
data.legal_entities[].registered_address.district	String	Yes	District
data.legal_entities[].registered_address.state_code	String	Yes	Two-letter state code
data.legal_entities[].registered_address.pincode	String	Yes	Six-digit postal code
data.legal_entities[].registered_address.country_code	String	Yes	Country code (e.g., `IN`)
data.legal_entities[].same_address	Boolean	No	If true, correspondence address same as registered
data.legal_entities[].correspondence_address	Object	No	Correspondence address (same structure as registered_address)
data.legal_entities[].related_persons	Array	Yes	Directors, signatories, beneficial owners
data.legal_entities[].related_persons[].prefix	String	Yes	Name prefix (`MR`, `MS`, etc.)
data.legal_entities[].related_persons[].first_name	String	Yes	First name
data.legal_entities[].related_persons[].middle_name	String	No	Middle name
data.legal_entities[].related_persons[].last_name	String	Yes	Last name
data.legal_entities[].related_persons[].din	String	No	Director Identification Number
data.legal_entities[].related_persons[].pan	String	No	PAN of the related person
data.legal_entities[].related_persons[].dob	String	Yes	Date of birth (`YYYY-MM-DD`)
data.legal_entities[].related_persons[].gender	String	Yes	`MALE`, `FEMALE`, or `OTHER`
data.legal_entities[].related_persons[].relationship_type	String	Yes	`DIRECTOR`, `SIGNATORY`, `BENEFICIAL_OWNER`, etc.
data.legal_entities[].related_persons[].mobile_number	String	No	Mobile number
data.legal_entities[].related_persons[].email	String	No	Email address
data.legal_entities[].related_persons[].address	Object	No	Address of the related person
data.legal_entities[].identity_documents	Array	Yes	Entity identity documents
data.legal_entities[].identity_documents[].id_number	String	Yes	Document number
data.legal_entities[].identity_documents[].type	String	Yes	`CERTIFICATE_OF_INCORPORATION`, `REGISTRATION_CERTIFICATE`, `PAN`, etc.
data.legal_entities[].images	Array	No	Entity document images
data.legal_entities[].images[].image	String	Yes	Base64-encoded image data
data.legal_entities[].images[].type	String	Yes	Image/document type

Example Request

{
    "data": {
        "purpose": "For regulatory compliance",
        "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": "123 Business Park, Sector 5",
                    "city": "New Delhi",
                    "district": "North Delhi",
                    "state_code": "DL",
                    "pincode": "110001",
                    "country_code": "IN"
                },
                "same_address": true,
                "related_persons": [
                    {
                        "prefix": "MR",
                        "first_name": "Vineet",
                        "last_name": "Kapoor",
                        "din": "1234567",
                        "pan": "ABCPK1234L",
                        "dob": "1996-02-29",
                        "gender": "MALE",
                        "relationship_type": "DIRECTOR",
                        "mobile_number": "9876543210",
                        "email": "vineet@example.com"
                    }
                ],
                "identity_documents": [
                    {
                        "id_number": "U72900DL2019PTC349962",
                        "type": "CERTIFICATE_OF_INCORPORATION"
                    }
                ],
                "images": [
                    {
                        "image": "base64encodeddata...",
                        "type": "CERTIFICATE_OF_INCORPORATION"
                    }
                ]
            }
        ]
    }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Response payload
data.client_id	String	Unique identifier for tracking this upload
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_upload_aBcDeFgHiJkLmNoPqRsT",
        "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

Server Error

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

The JWT token is missing, expired, or invalid.

Heads Up

Permission -- Requires ckyc-legal-upload (separate from individual ckyc-upload).

Mutual exclusivity -- Requests must contain legal_entities only. Do not mix with individuals.

No separate file upload -- Unlike the individual flow, document images are included in the initialize request itself (Base64 encoded).

Billing -- Billed per legal entity record in the batch (ckyc_legal_upload).

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

State machine -- After initialization, the request moves through pending → started → ready_to_upload → uploading → uploaded → upload_succeeded/upload_failed. 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/upload' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "data": { "purpose": "For regulatory compliance", "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": "123 Business Park, Sector 5", "city": "New Delhi", "district": "North Delhi", "state_code": "DL", "pincode": "110001", "country_code": "IN" }, "same_address": true, "related_persons": [ { "prefix": "MR", "first_name": "Vineet", "last_name": "Kapoor", "din": "1234567", "pan": "ABCPK1234L", "dob": "1996-02-29", "gender": "MALE", "relationship_type": "DIRECTOR", "mobile_number": "9876543210", "email": "vineet@example.com" } ], "identity_documents": [ { "id_number": "U72900DL2019PTC349962", "type": "CERTIFICATE_OF_INCORPORATION" } ], "images": [ { "image": "base64encodeddata...", "type": "CERTIFICATE_OF_INCORPORATION" } ] } ] } }'

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

CKYC Legal Upload

CKYC Legal Upload#

Description#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Code Samples#

Request

Responses

CKYC Legal Upload

Description

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Code Samples