Request Format:

Content-Type: multipart/form-data
Form field name: file
File type: CSV (.csv)

General Features:

Process up to 5,000 KYC records in a single batch
Asynchronous processing with status tracking
Automatic idempotency to prevent duplicate uploads
Maximum file size: 10 MB
Maximum records: 5,000 rows per batch
File encoding: UTF-8

Processing Timeline:

Upload: Immediate validation and storage
Queued: 0-10 minutes (status: pending)
Processing: Variable time based on batch size and provider limits (status: in_progress)
Completed: All records processed (status: completed)

Provider-Specific Details

Sumsub (`X-Provider: sumsub`)

CSV Format:

externalId,shareToken,applicantLevel
ef88fd57-26cf-415d-a112-941732c55350,eyJhbGci...,levelKyc
b1234567-89ab-cdef-0123-456789abcdef,eyJhbGci...,levelKyc

Required Columns:

externalId: UUID of existing entity in the system
shareToken: Valid share token from Sumsub

Optional Columns:

applicantLevel: Sumsub verification level (e.g., levelKyc, basic-kyc-level). If omitted, uses Sumsub's default level.

Rate Limits:

7 requests/second to Sumsub API
Processing time: Variable based on batch size and provider limits

Important Notes:

Each externalId must correspond to an existing entity (created via POST /entity)
Share tokens must be valid and not expired
If applicantLevel is provided but not configured in Reap's Sumsub account, processing will fail for that record

Use the returned batchId to monitor processing status via the GET endpoint.

Headers

X-Provider

Required: Yes Type: string Enum: sumsub

KYC provider identifier. Determines the expected CSV format and processing behavior. Currently supported: sumsub. Additional providers may be added in the future.

Example: sumsub

Idempotency-Key

Required: Yes Type: string

Unique key to prevent duplicate uploads. Use a combination of timestamp and UUID for uniqueness (e.g., batch-2024-01-15-uuid-v4)

Example: batch-2024-01-15-550e8400-e29b-41d4-a716-446655440000

Request Body

Upload a CSV file containing KYC batch data using multipart/form-data encoding.

Field: file Type: binary Required: Yes

CSV file containing KYC batch data. Format is provider-specific (see Provider-Specific Details section above). Use form field name "file" when uploading.

Response: 201 Created

Batch file uploaded successfully and queued for processing.

Response Fields:

batchId: Unique identifier for the batch upload. Use this ID to check processing status.
businessUuid: UUID of the business that uploaded this batch.
status: Current processing status of the batch. Always "pending" immediately after upload.
totalRecords: Total number of records found in the uploaded CSV file.
message: Human-readable message about the upload status.
createdAt: ISO 8601 timestamp when the batch was uploaded.

Next Steps:

Save the returned batchId
Wait 1-2 minutes before checking status
Poll the GET endpoint every 30-60 seconds to monitor progress
Processing will complete within 10-20 minutes for large batches

Example Response:

{
  "batchId": "f208a887-9fa6-4447-a52b-c1d6e089536f",
  "businessUuid": "64f6821b-c06a-49e6-aeba-477bb6a1bd11",
  "status": "pending",
  "totalRecords": 19,
  "message": "File uploaded successfully. Processing will start shortly.",
  "createdAt": "2025-10-08T11:40:20.796Z"
}

Response: 400 Bad Request

Invalid request - validation errors, missing headers, or invalid file format. Validation rules are provider-specific.

Error: File Too Large (General)

{
  "code": "0701010100",
  "message": "File size exceeds the maximum limit of 10 MB",
  "parameter": ""
}

Error: Too Many Rows in CSV (General)

{
  "code": "0701010100",
  "message": "File contains too many rows, limit is 5000",
  "parameter": ""
}

Error: CSV Validation Failed (Provider-specific)

{
  "code": "0701010200",
  "message": "CSV validation failed: 2 error(s) found.\nRow 5: Missing required field 'shareToken'\nRow 12: Missing required field 'externalId'",
  "parameter": ""
}

Error: Missing X-Provider Header

{
  "code": "0701010200",
  "message": "Valid X-Provider header is required",
  "parameter": ""
}

Error: Missing Idempotency-Key Header

{
  "code": "0701010200",
  "message": "Idempotency-Key header is required",
  "parameter": ""
}

Error: No File Provided

{
  "code": "0701010200",
  "message": "No files provided in the request",
  "parameter": ""
}

Error: Duplicate Upload Detected

{
  "code": "0701010300",
  "message": "A request with this idempotency key has already been processed",
  "parameter": ""
}

Response: 401 Unauthorized

Authentication required or invalid API key.

Error: Missing API Key

{
  "code": "0000000100",
  "message": "Invalid Authorization: missing API key",
  "parameter": ""
}

Error: Invalid API Key

{
  "code": "0000000200",
  "message": "Invalid Authorization",
  "parameter": ""
}

Response: 500 Internal Server Error

Internal server error during file upload or validation.