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:

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

Provider-Specific Details

Sumsub (X-Provider: sumsub)

CSV Format:

externalId,shareToken,applicantLevel,cardProcessorPublicToken
ef88fd57-26cf-415d-a112-941732c55350,eyJhbGci...,levelKyc,cpt-1
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.
• cardProcessorPublicToken: unique card processor public token to associate with the entity

Rate Limits:

• 10 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:

1. Save the returned batchId
2. Wait 1-2 minutes before checking status
3. Poll the GET endpoint every 30-60 seconds to monitor progress
4. 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": ""
}

{
  "code": "0701010200",
  "message": "duplicate cardProcessorPublicToken found",
  "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.