CKYC SFTP Flow (Bulk)#
Overview#
The CKYC Bulk APIs handle high-volume KYC operations via SFTP integration with CERSAI. Unlike the API Flow (which processes one record at a time via OTP), the SFTP Flow lets you submit, update, and download CKYC records in bulk - for both individuals and legal entities.Surepass handles the complexity: file building, encryption, SFTP upload/download, acknowledgment polling, and response parsing. You interact via simple REST APIs.Parent Category: CKYC
Sub-categories: Individual Entity, Legal Entity
How It Works#
What Surepass abstracts away:CSV/XML file building from your JSON request
Image processing and compression
AES encryption with your keystore
Acknowledgment polling and response file retrieval
Response decryption and parsing
Operations#
Upload & Update#
| Operation | Individual | Legal Entity | Description |
|---|
| Upload (new records) | POST /api/v1/ckyc-upload/upload/initialize | POST /api/v1/ckyc-upload/legal/upload | Register new CKYC records |
| Update (existing records) | POST /api/v1/ckyc-upload/update/initialize | POST /api/v1/ckyc-upload/legal/update | Update existing CKYC records |
| Upload File | POST /api/v1/ckyc-upload/upload/upload-file or POST /api/v1/ckyc-upload/update/upload-file | - | Alternate ZIP entrypoint for new uploads or updates |
| Status | POST /api/v1/ckyc-upload/update/status (status_type=upload|update) | POST /api/v1/ckyc-upload/legal/upload/status | Check processing status |
| Status Check (detailed) | POST /api/v1/ckyc-upload/update/status-check (status_type=upload|update) | POST /api/v1/ckyc-upload/legal/upload/status-check | Merged request + response data |
Bulk Download#
| Operation | Individual | Legal Entity | Description |
|---|
| Initialize | POST /api/v1/ckyc-upload/download/initialize | POST /api/v1/ckyc-upload/legal/download/initialize | Start bulk download |
| Status | POST /api/v1/ckyc-upload/download/status | POST /api/v1/ckyc-upload/legal/download/status | Poll download progress |
Management & Monitoring#
| Operation | Individual | Legal Entity | Description |
|---|
| List Clients | GET /api/v1/ckyc-upload/get-client-details | GET /api/v1/ckyc-upload/legal/get-client-details | Paginated list of upload/update requests |
| List Bulk Downloads | GET /api/v1/ckyc-upload/get-bulk-download-clients | GET /api/v1/ckyc-upload/legal/get-bulk-download-clients | Paginated list of download requests |
| Chart Data | GET /api/v1/ckyc-upload/chart-data | GET /api/v1/ckyc-upload/legal/chart-data | Time-series data (7/15/30 days) |
| SFTP Health | GET /api/v1/ckyc-upload/sftp-health | - | SFTP connectivity status |
Upload/Update Workflow#
For individual upload/update batches, choose one request format to start a batch:upload-file is not a follow-up call on an initialized batch. It creates a new batch by parsing the ZIP into the same internal payload used by the initialize endpoints.States#
| State | Description |
|---|
pending | Request accepted, not yet processing |
started | Processing has begun |
ready_to_upload | Files built, ready for SFTP upload |
uploading | Files being uploaded to CERSAI via SFTP |
uploaded | Upload complete, waiting for acknowledgment |
upload_succeeded | CERSAI accepted the batch |
upload_failed | Processing failed |
Sub-States#
For more granular tracking, use the sub_state field:| Sub-state | Description |
|---|
initiated | Request registered |
preparing_files | Building CSV/XML and processing images |
files_ready | Files built and encrypted |
uploading_to_cersai | SFTP transfer in progress |
waiting_ack | Upload complete, waiting for CERSAI acknowledgment |
batch_accepted | CERSAI accepted the batch for processing |
checker_approved | Batch approved by CERSAI checker |
batch_rejected | Batch rejected by CERSAI |
checker_rejected | Rejected by CERSAI checker |
processing_error | Error during file preparation |
upload_error | Error during SFTP upload |
Bulk Download Workflow#
Submit an array of CKYC IDs with verification parameters (DOB or mobile number). Poll the status endpoint until results are available.Prerequisites#
| Requirement | Description |
|---|
| FI Code | Financial Institution code issued by CERSAI |
| Private Key / Keystore | Must be provisioned for your account before you start integration |
| SFTP Configuration | Must be enabled for your account before bulk SFTP operations can be used |
| JWT Token | Bearer token for API authentication |
| Permission | ckyc-upload for individual, ckyc-legal-upload for legal entities |
Billing - Bulk operations are billed per individual/entity record in the batch, not per API call.
Record TTL - Upload/update records expire after 180 days (6 months).
Rate limiting - Bulk download status polling is rate-limited. Don't poll more frequently than every 30 seconds.
Mutual exclusivity - Upload requests must contain either individuals OR legal_entities, never both.
Sub-Categories#
Individual Entity
Bulk upload, update, and download of individual CKYC records. Includes all standard fields: personal details, addresses, identity documents, photographs, and verifier information.Legal Entity
Bulk operations for corporate/legal entity CKYC records. Includes entity details, related persons (directors, signatories, beneficial owners), constitution type, and incorporation information.