Feel free to reach techsupport@surepass.io for any technical support or guidance.
Legal Entity
Legal Entity — SFTP Flow
Overview
legal_entities[] instead of individuals[], with entity-specific fields like constitution type, incorporation details, TIN/GST, and related persons (directors, signatories, beneficial owners).Category Details
Permission required:
ckyc-legal-uploadAPIs: Legal Upload, Legal Update, Legal Upload Status, Legal Upload Status Check, Legal Bulk Download Initialize, Legal Bulk Download Status, Get Legal Client Details, Get Legal Bulk Download Clients, Legal Chart Data
Endpoints
Upload & Update
| Endpoint | Method | Description |
|---|---|---|
/ckyc-upload/legal/upload | POST | Register new legal entity CKYC records |
/ckyc-upload/legal/update | POST | Update existing legal entity CKYC records |
/ckyc-upload/legal/upload/status | POST | Check processing status of an upload/update request |
/ckyc-upload/legal/upload/status-check | POST | Detailed status with merged request + response data |
Bulk Download
| Endpoint | Method | Description |
|---|---|---|
/ckyc-upload/legal/download/initialize | POST | Start a bulk download of multiple legal entity records |
/ckyc-upload/legal/download/status | POST | Poll download progress and retrieve results |
Management
| Endpoint | Method | Description |
|---|---|---|
/ckyc-upload/legal/get-client-details | GET | List all legal upload/update requests with pagination |
/ckyc-upload/legal/get-bulk-download-clients | GET | List all legal bulk download requests |
/ckyc-upload/legal/chart-data | GET | Time-series chart data for legal entity operations |
Upload / Update Workflow
Step 1: Initialize
POST /ckyc-upload/legal/update (for existing records)
POST /ckyc-upload/legal/upload (for new records)data.purpose -- Purpose of the CKYC operationdata.verifier -- Verifier details (name, designation, branch, employment code, organization)data.legal_entities[] -- Array of legal entity records with:client_id and initial state (pending).legal_entities only. Do not mix with individuals in the same request.:::
Step 2: Poll Status
upload_succeeded or upload_failed):POST /ckyc-upload/legal/upload/statusPOST /ckyc-upload/legal/upload/status-checkStates & Sub-States
Bulk Download Workflow
Step 1: Initialize
POST /ckyc-upload/legal/download/initializeckyc_id -- CKYC Number or Reference ID (from Search API)dob -- Date of incorporation (conditional)pincode -- Registered pincode (conditional, alternative to dob)Step 2: Poll Status
POST /ckyc-upload/legal/download/statusManagement Endpoints
List Requests
GET /ckyc-upload/legal/get-client-details?page=1&page_size=20&status_type=upload| Parameter | Type | Required | Description |
|---|---|---|---|
| page | int | No | Page number (default: 1) |
| page_size | int | No | Results per page (default: 20) |
| status_type | string | Yes | "upload" or "update" |
| start_date | string | No | Filter by start date |
| end_date | string | No | Filter by end date |
| state | string | No | Filter by state enum |
| search | string | No | Search by client_id or batch_file_name |
List Bulk Downloads
GET /ckyc-upload/legal/get-bulk-download-clients?page=1&page_size=20Chart Data
GET /ckyc-upload/legal/chart-data?days=30&type=upload| Parameter | Type | Required | Description |
|---|---|---|---|
| days | int | No | Time range: 7, 15, or 30 (default: 30) |
| type | string | Yes | "update", "upload", or "download" |
Key Differences from Individual Flow
| Aspect | Individual | Legal Entity |
|---|---|---|
| Permission | ckyc-upload | ckyc-legal-upload |
| Request array | individuals[] | legal_entities[] |
| Entity fields | Personal details, DOB, gender | Constitution type, incorporation date, TIN/GST, place of incorporation |
| Related persons | Family details (father/mother/spouse) | Directors, signatories, beneficial owners (with DIN) |
| Download auth | DOB or mobile number | DOB or pincode |
| Upload file | Separate /upload-file endpoint | Included in initialize request |
| Billing code | ckyc_upload / ckyc_update | ckyc_legal_upload / ckyc_legal_update |
Heads Up