CKYC Legal Entity Download

Endpoint Overview

POST /api/v1/ckyc/v3/download/legal

Description

Download a legal entity CKYC record using ckyc_identifier from legal search and a matching authentication factor. This is a single-step download flow. It does not use OTP.

Use this endpoint after POST /api/v1/ckyc/v3/search/legal. The search response gives you records[].ckyc_identifier; pass that value here.

Authentication

Environment	Base URL
Sandbox	`https://sandbox.surepass.app`
Production	`https://kyc-api.surepass.app`

Header	Required	Description
`Authorization`	Yes	Bearer token. Format: `Bearer YOUR_JWT_TOKEN`
`Content-Type`	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`ckyc_identifier`	String	Yes	Canonical CKYC identifier from legal search. This can be a CKYC reference ID such as `LEFILB20063639` or a CKYC number, depending on what search returned.
`auth_factor_type`	String	Yes	Type of authentication factor. The API normalizes case, spaces, and hyphens to lowercase snake_case.
`auth_factor`	String	Yes	Value of the selected authentication factor.

Supported `auth_factor_type` Values

`auth_factor_type` value	Description	`auth_factor` format
`date_of_incorporation`	Date of incorporation	Date value accepted by CKYC, commonly `DD-MM-YYYY` or `YYYY-MM-DD`
`mobile_number`	Registered mobile number	10-digit mobile number
`email`	Registered email	Email address
`pincode`	Registered or local pincode	6-digit pincode

Example Request

{
  "ckyc_identifier": "LEFILB20063639",
  "auth_factor_type": "date_of_incorporation",
  "auth_factor": "2019-05-10"
}

Response

Parameter	Type	Description
`data.client_id`	String	SurePass transaction ID for this legal download.
`data.status`	String	`downloaded` when the download completed.
`data.ckyc_download_data`	Object	Full legal entity CKYC record. Present when `status` is `downloaded`.
`status_code`	Integer	HTTP status code.
`success`	Boolean	Whether the operation succeeded.
`message`	String	Human-readable status.
`message_code`	String	Machine-readable status.

Download Data Structure

ckyc_download_data contains:

Field	Type	Description
`record_counts`	Object	Download/update counters returned by CKYC.
`personal_details`	Object	Legal entity identity, address, contact, KYC, and registration details.
`identity_details`	Array	Entity identity documents.
`related_persons`	Array	Directors, promoters, partners, trustees, beneficial owners, signatories, and other related persons returned by CKYC.
`image_details.image`	Array	Entity document images, if any.

`personal_details`

Field	Description
`full_name`	Full registered name from CKYC.
`organization_name`	Organization name. Uses `org_name` when present, otherwise full name.
`organization_code`	Organization code when returned.
`dob`	Same date as date of incorporation for legal entities. Normalized to `YYYY-MM-DD` when parseable.
`date_of_incorporation`	Date of incorporation normalized to `YYYY-MM-DD` when parseable.
`date_of_commencement_of_business`	Date business commenced, normalized when parseable.
`pan`	Entity PAN.
`constitution_type`	Display label for constitution type, for example `Private Limited Company`.
`constitution_type_others`	Free-text constitution type when CKYC marks it as Other.
`ipv_flag`	In-person verification flag as returned by CKYC.
`remarks`	Registry remarks.
`permanent_address_line_1`, `permanent_address_line_2`, `permanent_address_line_3`	Permanent address lines.
`permanent_address_district`, `permanent_address_city`, `permanent_address_state`, `permanent_address_pin`, `permanent_address_country`	Permanent address components.
`correspondence_address_line_1`, `correspondence_address_line_2`, `correspondence_address_line_3`	Correspondence address lines.
`correspondence_address_district`, `correspondence_address_city`, `correspondence_address_state`, `correspondence_address_pin`, `correspondence_address_country`	Correspondence address components.
`same_as_permanent_address`	Whether correspondence address is same as permanent address, as returned by CKYC.
`proof_of_address`	Display label for entity proof of address.
`permanent_proof_of_address`	Display label for permanent proof of address.
`permanent_proof_of_address_others`	Free-text permanent proof of address when CKYC marks it as Other.
`correspondence_proof_of_address`	Display label for correspondence proof of address.
`email`, `email_secondary`	Registered email addresses.
`mobile_code`, `mobile_number`	Primary mobile code and number.
`mobile_code_secondary`, `mobile_number_secondary`	Secondary mobile code and number.
`fax_code`, `fax_number`	Fax details when returned.
`office_std_code`, `office_phone_number`	Office telephone details.
`declaration_date`, `declaration_place`	Declaration metadata.
`kyc_employee_code`, `kyc_designation`, `kyc_branch`, `kyc_name`, `kyc_date`	KYC officer and branch metadata.
`total_identity_records`	Count of identity records.
`total_image_records`	Count of image records.
`total_related_persons`	Count of related persons.
`ckyc_number`	Legal entity CKYC number.
`ckyc_reference_id`	CKYC reference ID, usually starting with `LE`.
`gst_tin_number`, `gst_country`	GST/TIN details when returned.
`country_of_incorporation`, `place_of_incorporation`	Incorporation location details.
`document_submission_type`	Raw document submission code, for example `01`.
`document_submission_type_value`	Display label for document submission type, for example `Certified Copies`.

Unknown or less common CKYC fields may also be included.

`identity_details`

Each entity identity document is normalized into this shape:

Field	Description
`identity_number`	Identity document number.
`identity_type`	App-facing enum-like value, for example `PAN`, `CERTIFICATE_OF_INCORPORATION`, or `REGISTRATION_CERTIFICATE`.
`identity_type_code`	Raw CERSAI identity-type code, for example `C`, `02`, or `03`.
`identity_type_value`	Human-readable document label.
`id_verification_status`	`YES` when CKYC status code is `01`, otherwise `NO`.

`related_persons`

The response keeps CKYC related-person keys and adds display-label companions for selected coded fields.

Field	Description
`sequence_no`	Related person sequence number.
`rel_type`	Raw relationship type code.
`rel_type_value`	Display label such as `Director`, `Promoter`, `Partner`, `Trustee`, `Authorised Signatory`, or `Beneficial Owner`.
`ckyc_no`	Related person's CKYC number when returned.
`prefix`, `fname`, `mname`, `lname`	Related person's name parts.
`dob`	Date of birth as returned by CKYC.
`gender`	Raw gender code when returned.
`gender_value`	Display label such as `MALE`, `FEMALE`, or `TRANSGENDER`.
`pan`	Related person's PAN.
`add_line1`, `add_line2`, `add_line3`, `add_city`, `add_district`, `add_state`, `add_country`, `add_pin`	Address fields.
`perm_poi_type`	Raw permanent proof type code.
`perm_poi_type_value`	Display label for `perm_poi_type`.
`same_as_perm_flag`	Whether correspondence address is same as permanent address.
`corres_add_line1`, `corres_add_line2`, `corres_add_line3`, `corres_add_city`, `corres_add_dist`, `corres_add_state`, `corres_add_country`, `corres_add_pin`	Correspondence address fields.
`corres_poi_type`	Raw correspondence proof type code.
`corres_poi_type_value`	Display label for `corres_poi_type`.
`mob_code`, `mob_num`	Mobile code and number.
`email`	Email address.
`photo_type`, `photo_data`	Related person's photo type and Base64 data.
`perm_poi_image_type`, `perm_poi_data`	Permanent proof image type and Base64 data.
`corres_poi_image_type`, `corres_poi_data`	Correspondence proof image type and Base64 data.
`resi_status`, `resi_status_value`	Raw and display residence status when returned.
`dis_type`, `dis_type_value`	Raw and display disability type when returned.

Images

image_details.image is always an array when present.

Field	Description
`image_code`	Display label for image type, for example `Certificate of Incorporation/Formation` or `Registration Certificate`.
`image_type`	File type, for example `jpg` or `pdf`.
`image_data`	Base64-encoded image or document data.
`global_flag`	Raw global/local flag when returned.
`global_flag_value`	Display label for `global_flag`.

Example Successful Response

{
  "data": {
    "client_id": "ckyc_realtime_legal_download_QxLkPz",
    "status": "downloaded",
    "ckyc_download_data": {
      "record_counts": {
        "download_count": 1,
        "update_count": 0
      },
      "personal_details": {
        "full_name": "Acme Technologies Private Limited",
        "dob": "2019-05-10",
        "date_of_incorporation": "2019-05-10",
        "date_of_commencement_of_business": "2019-05-10",
        "pan": "ABCAA1234A",
        "constitution_type": "Private Limited Company",
        "permanent_address_line_1": "101 Business Park",
        "permanent_address_city": "Mumbai",
        "permanent_address_state": "Maharashtra",
        "permanent_address_pin": "400001",
        "permanent_address_country": "India",
        "correspondence_address_line_1": "101 Business Park",
        "correspondence_address_city": "Mumbai",
        "correspondence_address_state": "Maharashtra",
        "correspondence_address_pin": "400001",
        "correspondence_address_country": "India",
        "same_as_permanent_address": "Y",
        "email": "contact@acme.example",
        "email_secondary": "ops@acme.example",
        "mobile_code": 91,
        "mobile_number": "9876543210",
        "mobile_code_secondary": 91,
        "mobile_number_secondary": "9123456780",
        "declaration_date": "2023-08-16",
        "declaration_place": "Mumbai",
        "organization_name": "Acme Technologies Private Limited",
        "organization_code": "ACME001",
        "kyc_date": "2023-08-16",
        "proof_of_address": "Proof of Possession of Aadhaar",
        "permanent_proof_of_address": "Proof of Possession of Aadhaar",
        "correspondence_proof_of_address": "Proof of Possession of Aadhaar",
        "total_identity_records": 1,
        "total_image_records": 1,
        "total_related_persons": 2,
        "ckyc_number": "22345678901234",
        "ckyc_reference_id": "LEMOCK12345678",
        "country_of_incorporation": "India",
        "place_of_incorporation": "Mumbai",
        "document_submission_type": "01",
        "document_submission_type_value": "Certified Copies"
      },
      "identity_details": [
        {
          "identity_number": "U12345MH2019PTC123456",
          "identity_type": "CERTIFICATE_OF_INCORPORATION",
          "identity_type_code": "02",
          "identity_type_value": "Certificate of Incorporation/Formation",
          "id_verification_status": "YES"
        }
      ],
      "related_persons": [
        {
          "sequence_no": 1,
          "rel_type": 4,
          "rel_type_value": "Director",
          "fname": "Rohan",
          "lname": "Shah",
          "dob": "12-09-1986",
          "gender": "M",
          "gender_value": "MALE",
          "pan": "FGHIJ4321K",
          "mob_code": 91,
          "mob_num": "9811111111",
          "email": "rohan.shah@acme.example"
        }
      ],
      "image_details": {
        "image": [
          {
            "image_code": "Certificate of Incorporation/Formation",
            "image_type": "pdf",
            "image_data": "BASE64_DOCUMENT_DATA"
          }
        ]
      }
    }
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Common Errors

Message Code	Meaning
`auth_factor_mismatch`	The submitted auth factor did not match CKYC records.
`auth_factor_not_found`	CKYC could not find the submitted auth factor for the identifier.
`daily_limit_exceeded`	CERSAI daily limit was reached.
`invalid_ckyc_number`	CKYC number format was rejected.
`invalid_ckyc_reference_id`	CKYC reference ID format was rejected.
`downstream_request_timeout`	CKYC realtime service timed out.

Code Samples

cURL

Python

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location 'https://kyc-api.surepass.app/api/v1/ckyc/v3/download/legal' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "ckyc_identifier": "22345678901234", "auth_factor_type": "date_of_incorporation", "auth_factor": "2019-05-10" }'

{ "data": { "client_id": "ckyc_realtime_legal_download_QxLkPz", "status": "downloaded", "ckyc_download_data": { "record_counts": { "download_count": 1, "update_count": 0 }, "personal_details": { "full_name": "Acme Technologies Private Limited", "dob": "2019-05-10", "date_of_incorporation": "2019-05-10", "date_of_commencement_of_business": "2019-05-10", "pan": "ABCAA1234A", "constitution_type": "Private Limited Company", "permanent_address_line_1": "101 Business Park", "permanent_address_city": "Mumbai", "permanent_address_state": "Maharashtra", "permanent_address_pin": "400001", "permanent_address_country": "India", "correspondence_address_line_1": "101 Business Park", "correspondence_address_city": "Mumbai", "correspondence_address_state": "Maharashtra", "correspondence_address_pin": "400001", "correspondence_address_country": "India", "same_as_permanent_address": "Y", "email": "contact@acme.example", "email_secondary": "ops@acme.example", "mobile_code": 91, "mobile_number": "9876543210", "mobile_code_secondary": 91, "mobile_number_secondary": "9123456780", "declaration_date": "2023-08-16", "declaration_place": "Mumbai", "organization_name": "Acme Technologies Private Limited", "organization_code": "ACME001", "kyc_date": "2023-08-16", "proof_of_address": "Proof of Possession of Aadhaar", "permanent_proof_of_address": "Proof of Possession of Aadhaar", "correspondence_proof_of_address": "Proof of Possession of Aadhaar", "total_identity_records": 1, "total_image_records": 1, "total_related_persons": 2, "ckyc_number": "22345678901234", "ckyc_reference_id": "LEMOCK12345678", "country_of_incorporation": "India", "place_of_incorporation": "Mumbai", "document_submission_type": "01", "document_submission_type_value": "Certified Copies" }, "identity_details": [ { "identity_number": "U12345MH2019PTC123456", "identity_type": "CERTIFICATE_OF_INCORPORATION", "identity_type_code": "02", "identity_type_value": "Certificate of Incorporation/Formation", "id_verification_status": "YES" } ], "related_persons": [ { "sequence_no": 1, "rel_type": 4, "rel_type_value": "Director", "fname": "Rohan", "lname": "Shah", "dob": "12-09-1986", "gender": "M", "gender_value": "MALE", "pan": "FGHIJ4321K", "mob_code": 91, "mob_num": "9811111111", "email": "rohan.shah@acme.example" } ], "image_details": { "image": [ { "image_code": "Certificate of Incorporation/Formation", "image_type": "pdf", "image_data": "BASE64_DOCUMENT_DATA" } ] } } }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Authentication#

Request Body#

Supported auth_factor_type Values#

Example Request#

Response#

Download Data Structure#

personal_details#

identity_details#

related_persons#

Images#

Example Successful Response#

Common Errors#

Code Samples#

Request

Responses