Endpoints

Method	URL	Description
POST	`/entity/kyc/import/batch`	Upload KYC batch file
GET	`/entity/kyc/import/batch/{batchId}`	Get KYC batch status

Upload KYC Batch File

POST /entity/kyc/import/batch

Uploads a CSV file containing SumSub KYC records for batch processing.

Required Headers

Name	Type	Required	Description
`X-Provider`	string	Yes	KYC provider. Allowed value: `sumsub`
`Idempotency-Key`	string	Yes	Unique key to prevent duplicate uploads

Request Body (multipart/form-data)

Field	Type	Required	Description
`file`	binary	Yes	CSV file to upload

Response (201 Created)

{
  "batchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "businessUuid": "b1c2d3e4-f5a6-7890-bcde-fa1234567890",
  "status": "pending",
  "totalRecords": 150,
  "message": "Batch uploaded successfully",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Error Codes (400 Bad Request)

Code	Description
`kyc_batch.upload.file_too_large`	File exceeds the maximum allowed size
`kyc_batch.upload.invalid_data`	Invalid CSV format, missing provider header, missing idempotency key, or no file provided
`kyc_batch.upload.duplicate_file_or_content`	A file with the same content has already been uploaded

Other Responses

Status	Description
`401`	Unauthorized — missing or invalid API key
`500`	Internal server error

Get KYC Batch Status

GET /entity/kyc/import/batch/{batchId}

Retrieves the processing status and summary of a previously uploaded batch.

Path Parameters

Name	Type	Required	Description
`batchId`	string (UUID)	Yes	The ID of the batch to query

Response (200 OK)

{
  "batchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "totalRecords": 150,
  "processedRecords": 148,
  "failedRecords": 2,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:45:00.000Z",
  "startedAt": "2024-01-15T10:31:00.000Z",
  "completedAt": "2024-01-15T10:45:00.000Z",
  "summary": {
    "successfulRecords": 148,
    "errors": [
      {
        "rowNumber": 42,
        "error": "Invalid SumSub applicant ID",
        "entityData": {}
      }
    ]
  }
}

Batch Status Values

Status	Description
`pending`	Batch uploaded, awaiting processing
`in_progress`	Batch is currently being processed
`completed`	All records processed successfully
`failed`	Batch processing failed
`canceled`	Batch processing was canceled

Other Responses

Status	Description
`401`	Unauthorized — missing or invalid API key
`404`	Batch not found
`500`	Internal server error