SumSub KYC Data Sharing

Enable your organization to share verified KYC data with Reap in bulk using Sumsub’s Reusable KYC feature.

This process allows you to securely transfer thousands of verified applicants to Reap in a single operation.

1. Pre-Setup Requirements

Before you begin, please complete the following with Sumsub and Reap:

1. Sign the Sumsub Reusable KYC Agreement

   This authorizes your company as a donor of KYC data and Reap as the recipient.

2. Add Reap as a Recipient

   After signing the agreement, use the token provided by Reap to add us as an authorized recipient within your Sumsub account.

   (Refer to Sumsub’s documentation on how to set up Partners for exact steps.)

2. Prepare Your Applicant List

1. In your Sumsub dashboard, filter and export the list of applicants you want to share with Reap.

2. The CSV must include at least the following columns:

   externalId, applicantId
   

Note:

• Maximum 5,000 rows per file

• File size ≤ 10 MB

• Must be UTF-8 encoded and include a header row

3. Generate Share Tokens

Use the Python script provided by Reap to generate share tokens for each applicant.

• Input: Your exported CSV from Sumsub

• Output: A new CSV with the columns below:

  externalId, shareToken
  

The script automatically handles rate-limiting and retries.

Once generated, this final CSV is ready to share with Reap.

4. Share with Reap

Send the generated CSV securely to your Reap contact or integration endpoint.

Reap will handle the batch upload, verification, and processing on our side.

Processing Time:

Uploads begin processing within ~10 minutes and typically complete in 2–10 minutes per 1,000 records.

Two Integration Options:

• Automated Workflow (Recommended) - Use our Python CLI tool for end-to-end automation
• Manual Integration - Direct API integration for custom implementations

This guide covers both approaches, from generating share tokens to monitoring batch processing results.

Workflow Overview

Option 1: Complete Automated Workflow (Recommended)

If you have existing Sumsub applicant data and want a fully automated solution, use our kyc-share-token tool:

graph LR
    A[Input CSV<br/>applicantId, externalId] -->|Python CLI Tool<br/>Auto rate limiting<br/>Auto retries| B[Output CSV<br/>externalId, shareToken]
    B -->|Upload to<br/>Reap API| C[Batch Processing]
    C -->|Monitor<br/>Status| D[Complete]

    style A fill:#3b82f6,stroke:#1e40af,stroke-width:3px,color:#fff
    style B fill:#8b5cf6,stroke:#5b21b6,stroke-width:3px,color:#fff
    style C fill:#f59e0b,stroke:#d97706,stroke-width:3px,color:#fff
    style D fill:#10b981,stroke:#059669,stroke-width:3px,color:#fff

This tool handles everything: generating share tokens from Sumsub, CSV validation, rate limiting, error handling, and prepares the file ready for upload.

See: kyc-share-token repository for complete instructions

Option 2: Manual API Integration

If you prefer to integrate directly with the API or already have share tokens:

graph TD
    A[Prepare CSV File] -->|Step 1 - Create CSV with<br/>externalId, shareToken, applicantLevel optional<br/>Max 5000 rows, 10 MB| B[Upload Batch]
    B -->|Step 2 - POST /entity/kyc/import/batch<br/>Returns batchId| C[PENDING]
    C -->|0-10 minutes<br/>Waiting for processor| D[PROCESSING]
    D -->|2-3 minutes per 1000 records<br/>Rate ~7 records/second| E[COMPLETED]
    E -->|Step 3 - GET /entity/kyc/import/batch/batchId<br/>View results and statistics| F[Review Results]

    style A fill:#6366f1,stroke:#4338ca,stroke-width:3px,color:#fff
    style B fill:#a855f7,stroke:#7e22ce,stroke-width:3px,color:#fff
    style C fill:#eab308,stroke:#ca8a04,stroke-width:3px,color:#fff
    style D fill:#f97316,stroke:#c2410c,stroke-width:3px,color:#fff
    style E fill:#22c55e,stroke:#16a34a,stroke-width:3px,color:#fff
    style F fill:#0ea5e9,stroke:#0369a1,stroke-width:3px,color:#fff

Table of Contents

1. Workflow Overview
2. Key Features
3. Prerequisites
4. Supported Providers
5. Quick Start
6. Step 1: Prepare Your CSV File
7. Step 2: Upload Your Batch
8. Step 3: Monitor Batch Processing
9. Error Handling
10. Best Practices
11. FAQ
12. Complete Integration Example
13. Support

Key Features

• Bulk Processing: Upload up to 5,000 KYC records in a single batch
• Asynchronous Processing: Files are processed in the background without blocking your application
• Idempotency: Duplicate uploads are automatically prevented
• Progress Tracking: Monitor batch processing status in real-time
• Error Handling: Detailed error information for failed records
• Rate Limiting: Automatic throttling to comply with provider limits (7 requests/second)

Prerequisites

Before you begin, ensure you have:

1. API Access: Valid authentication credentials with appropriate permissions
2. Entity Records: IMPORTANT - Entities must already exist in the system (created via POST /entity). The batch upload verifies existing entities, it does not create new ones.
3. KYC Provider: Access to a supported KYC provider (currently Sumsub)
4. Share Tokens: Valid share tokens from your KYC provider for each entity

Important Note: This batch upload feature is for verifying existing entities only. Each externalId in your CSV must correspond to an entity that already exists in the system. If you need to create new entities, use the POST /entity endpoint first.

Supported Providers

Currently, the following KYC providers are supported:

Note: Additional providers may be added in future releases.

Quick Start

TL;DR - Get started in 3 simple steps:

1. Create CSV file with required columns: externalId, shareToken (and optional applicantLevel)

   csv

   externalId,shareToken,applicantLevel
   ef88fd57-26cf-415d-a112-941732c55350,eyJhbGci...,levelKyc

   Note: The applicantLevel column can be empty if you want to use Sumsub's default level.

2. Upload batch using the API:

   Bash

   curl -X POST https://api.reap.global/entity/kyc/import/batch \
     -H "Authorization: COMPLIANCE_API_KEY" \
     -H "X-Provider: sumsub" \
     -H "Idempotency-Key: batch-$(date +%s)-$(uuidgen)" \
     -F "file=@kyc_batch.csv"

3. Monitor progress by polling the status endpoint:

   Bash

   curl https://api.reap.global/entity/kyc/import/batch/{batchId} \
     -H "Authorization: COMPLIANCE_API_KEY"

Processing Time: 0-10 minutes to start, then ~2-3 minutes per 1,000 records

For detailed instructions, continue reading below.

Step 1: Prepare Your CSV File

Need to Generate Share Tokens?

If you need to generate share tokens from existing Sumsub applicant data, we provide an open-source Python CLI tool:

kyc-share-token - Generates share tokens from Sumsub applicant IDs with automatic rate limiting, retry logic, and resume functionality. The output CSV is ready for batch upload.

See the repository documentation for installation and usage instructions.

File Requirements

• Format: CSV (Comma-Separated Values)
• Maximum File Size: 10 MB
• Maximum Records: 5,000 rows per batch
• Encoding: UTF-8
• Header Row: Required (first row must contain column names)

CSV Structure for Sumsub

Your CSV file must contain the following columns:

Sample CSV File

With applicantLevel specified:

externalId,shareToken,applicantLevel
ef88fd57-26cf-415d-a112-941732c55350,eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U,levelKyc
b1234567-89ab-cdef-0123-456789abcdef,eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5ODc2NTQzMjEwIn0.qWfg3qN5kB8jP4sVnMhT0wR_KxL9m3N8oQfR5TUsE7A,levelKyc
c9876543-21fe-dcba-9876-543210fedcba,eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTU1NTU1NTU1In0.xYzR7vM2nP9kS6tWoNiV3aS_OyQ0n4P9rThV6XvxF8B,levelKyc

Without applicantLevel (uses Sumsub default):

externalId,shareToken
ef88fd57-26cf-415d-a112-941732c55350,eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U
b1234567-89ab-cdef-0123-456789abcdef,eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI5ODc2NTQzMjEwIn0.qWfg3qN5kB8jP4sVnMhT0wR_KxL9m3N8oQfR5TUsE7A
c9876543-21fe-dcba-9876-543210fedcba,eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTU1NTU1NTU1In0.xYzR7vM2nP9kS6tWoNiV3aS_OyQ0n4P9rThV6XvxF8B

Note: The applicantLevel column can be completely omitted. When not provided, Sumsub will use the default verification level configured for your account.

Best Practices for CSV Preparation

✅ Do:

• Use UUID format for externalId (matches your entity IDs)
• Ensure each externalId corresponds to an existing entity in the system
• Validate that share tokens are current and not expired
• Remove any empty rows or rows with missing data
• Use consistent column names (case-sensitive)
• Test with a small batch (10-50 records) first

❌ Don't:

• Include duplicate externalId values in the same file
• Use special characters or formatting in column names
• Exceed the 5,000 row limit
• Include BOM (Byte Order Mark) characters
• Use Excel-specific formatting (save as plain CSV)

CSV Checklist

Before uploading, verify your CSV file meets these requirements:

• File size ≤ 10 MB
• Row count ≤ 5,000 (excluding header)
• UTF-8 encoding
• Header row with required column names: externalId, shareToken (optional: applicantLevel)
• All externalId values are valid UUIDs of existing entities
• All required fields (externalId, shareToken) are present in every row
• No empty rows
• Saved as plain CSV (not Excel format)

Step 2: Upload Your Batch

Endpoint

POST /entity/kyc/import/batch

Required Headers

Request Body

The request body must be sent as multipart/form-data:

Example Request (cURL)

curl -X POST https://api.reap.global/entity/kyc/import/batch \
  -H "Authorization: COMPLIANCE_API KEY" \
  -H "X-Provider: sumsub" \
  -H "Idempotency-Key: batch-2024-01-15-550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@/path/to/your/kyc_batch.csv"

Note: For complete code examples in Python and JavaScript, see the kyc-share-token integration guide.

Success Response (201 Created)

{
  "batchId": "784d4045-c900-4050-aad6-8fe4c8d2fb16",
  "businessUuid": "a1234567-89ab-cdef-0123-456789abcdef",
  "status": "PENDING",
  "totalRecords": 1000,
  "message": "File uploaded successfully. Processing will start shortly.",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Response Fields

Important: Save the batchId - you'll need it to check the processing status!

What Happens Next?

After a successful upload:

1. ✅ Immediate: Your CSV file is validated and parsed
2. ⏳ 0-10 minutes: Batch enters the processing queue (status: PENDING)
3. ⚙️ Processing: Records are sent to KYC provider (status: PROCESSING)
4. ✅ Completion: All records processed (status: COMPLETED)

Expected Timeline:

• Small batches (< 100 records): 3-5 minutes total
• Medium batches (100-1,000 records): 5-10 minutes total
• Large batches (1,000-5,000 records): 10-20 minutes total

Step 3: Monitor Batch Processing

Processing Timeline

1. Upload (Immediate): Your CSV is validated and stored
2. Queued (0-10 minutes): Batch waits for the next processing cycle
3. Processing (Variable): Records are sent to the KYC provider
   • Rate: ~7 records per second (provider limit)
   • Duration: Approximately 2-3 minutes per 1,000 records
4. Completed (Final): All records processed

Batch Status Values

Check Batch Status

Endpoint

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

Example Request

curl -X GET https://api.reap.global/entity/kyc/import/batch/784d4045-c900-4050-aad6-8fe4c8d2fb16 \
  -H "Authorization: COMPLIANCE_API_KEY"

Success Response (200 OK)

{
  "batchId": "784d4045-c900-4050-aad6-8fe4c8d2fb16",
  "status": "COMPLETED",
  "totalRecords": 1000,
  "processedRecords": 995,
  "failedRecords": 5,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:45:00.000Z",
  "startedAt": "2024-01-15T10:35:00.000Z",
  "completedAt": "2024-01-15T10:45:00.000Z",
  "summary": {
    "successfulRecords": 990,
    "errors": []
  }
}

Response Fields

Error Handling

Quick Error Reference

Detailed Error Descriptions

Upload Errors (4xx Client Errors)

File Too Large (400)

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

Solution: Reduce file size or split into multiple batches

Too Many Rows (400)

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

Solution: Split your data into multiple batches of 5,000 rows or fewer

Invalid CSV Format (400)

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

Solution: Fix the CSV file according to the error messages. Ensure all required fields (externalId and shareToken) are present. Note that applicantLevel is optional and can be left empty.

Duplicate Upload (400)

{
  "code": "9999993401",
  "message": "This file has already been uploaded",
  "parameter": ""
}

or

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

Solution: This is expected behavior if you're retrying an upload. Use the original batchId to check status instead of re-uploading.

Missing Required Header (400)

{
  "code": "9999993400",
  "message": "valid X-Provider header is required",
  "parameter": ""
}

or

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

Solution: Ensure all required headers are included in your request

Missing File (400)

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

Solution: Ensure the file is properly attached to the multipart/form-data request

Retrieval Errors

Batch Not Found (404)

{
  "code": "9999993404",
  "message": "Batch not found",
  "parameter": ""
}

Possible Causes:

• Invalid batchId
• Batch belongs to a different business
• Batch was deleted

Solution: Verify the batchId and ensure you're using the correct business credentials

Authentication Errors (401)

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

Solution: Ensure your Compliance API key is valid and correct

Best Practices

1. Use the kyc-share-token Tool

For generating share tokens from Sumsub applicant data, use our open-source kyc-share-token tool. It handles:

• CSV validation and format checking
• Rate limiting (40 requests per 5 seconds)
• Automatic retries with exponential backoff
• Resume functionality for interrupted processing
• Comprehensive error reporting

2. Idempotency Key Management

Always generate unique idempotency keys to prevent accidental duplicate uploads:

# Good: Unique per upload attempt
batch-$(date +%s)-$(uuidgen)

# Bad: Reusing the same key
my-batch-upload  # Don't do this!

3. Batch Size Optimization

For optimal processing times:

• Small batches (< 100 records): 1-2 minutes
• Medium batches (100-1,000 records): 2-5 minutes
• Large batches (1,000-5,000 records): 5-15 minutes

Consider splitting very large datasets into multiple batches of 500-1,000 records for easier monitoring.

4. Handle Duplicate Upload Errors

Treat duplicate upload errors (code 9999993401) as success - use the original batchId to check status instead of re-uploading.

5. Polling Strategy

When monitoring batch status:

• Initial wait: 1-2 minutes before first check
• Polling interval: Every 30-60 seconds during processing
• Timeout: 30 minutes maximum for large batches

6. Common Pitfalls to Avoid

❌ Mistake: Uploading CSV with entities that don't exist yet ✅ Solution: Create entities first via POST /entity, then upload KYC batch

❌ Mistake: Using expired share tokens ✅ Solution: Generate fresh share tokens using kyc-share-token tool before upload

❌ Mistake: Polling too frequently (every second) ✅ Solution: Wait 1-2 minutes before first check, then poll every 30-60 seconds

❌ Mistake: Not handling duplicate upload errors gracefully ✅ Solution: Treat error code 9999993401 as success, use the original batchId

FAQ

How often are batches processed?

Batches are processed every 10 minutes by a scheduled processor. Your batch will begin processing within 10 minutes of upload.

Can I upload multiple batches simultaneously?

Yes, you can upload multiple batches. Each will be processed independently. However, be mindful of the provider's rate limits (7 requests/second shared across all batches).

What happens if some records fail?

The batch will continue processing remaining records. Failed records are counted in the failedRecords field, and successful records in successfulRecords. The overall batch status will still be COMPLETED.

How long are batch results retained?

Batch records are retained indefinitely unless explicitly deleted. You can query batch status at any time using the batchId.

Can I cancel a batch that's processing?

Currently, there is no cancellation feature. Once a batch starts processing, it will continue until completion.

What should I do if processing takes too long?

Processing time depends on batch size and provider response times. For batches over 2,000 records, processing may take 10-20 minutes. If a batch remains in PROCESSING state for over 30 minutes, contact support.

Can I get detailed error information for failed records?

Currently, the API returns aggregate error counts. Detailed per-record error information will be available in a future release. For now, check the entity requirement status for each externalId to see which records failed.

Troubleshooting Guide

Problem: "Batch not found" error when checking status

• Check: Verify you're using the correct batchId from the upload response
• Check: Ensure you're authenticated with the same business credentials used for upload
• Check: Confirm the batchId is a valid UUID

Problem: Upload succeeds but all records fail

• Possible Cause: Entities don't exist in the system
• Solution: Verify all externalId values correspond to existing entities

Problem: Batch stuck in PENDING for over 15 minutes

• Possible Cause: System issue or processor delay
• Solution: Contact support with your batchId

Problem: "Invalid CSV format" errors

• Solution: Ensure exact required column names (case-sensitive): externalId, shareToken
• Solution: Optional column: applicantLevel (can be omitted entirely)
• Solution: Check for empty rows or missing required values
• Solution: Verify file is UTF-8 encoded without BOM

Problem: Multipart upload fails with "No files provided"

• Solution: Ensure Content-Type: multipart/form-data header is set
• Solution: Verify file field name is file (lowercase)
• Solution: In Node.js, include ...form.getHeaders() in your headers

Complete Integration Example

For a complete end-to-end integration example including generating share tokens and uploading batches, see the kyc-share-token repository.

The repository includes:

• Complete workflow examples - From generating share tokens to uploading and monitoring batches
• Production-ready code - Battle-tested JavaScript/Node.js client implementations
• Error handling patterns - Comprehensive retry logic and error recovery strategies
• Integration guide - Step-by-step instructions with code samples

Key Resources:

• Full Integration Guide - Complete integration walkthrough
• README - Quick start and usage examples
• Code Examples - Sample CSV files and scripts

Quick Example:

# Step 1: Generate share tokens from Sumsub applicant data
python sumsub_share_token_generator.py input.csv output.csv

# Step 2: Upload the generated CSV to Reap KYC Batch Upload API
curl -X POST https://api.reap.global/entity/kyc/import/batch \
  -H "Authorization: COMPLIANCE_API_KEY" \
  -H "X-Provider: sumsub" \
  -H "Idempotency-Key: batch-$(date +%s)-$(uuidgen)" \
  -F "[email protected]"

# Step 3: Monitor the batch status
curl https://api.reap.global/entity/kyc/import/batch/{batchId} \
  -H "Authorization: COMPLIANCE_API_KEY"

For detailed JavaScript/Node.js client implementations and advanced usage patterns, refer to the repository documentation.

Support

If you encounter issues not covered in this guide:

1. Check Error Codes: Refer to the error handling section above
2. Review Logs: Check your application logs for detailed error messages
3. Contact Support: Reach out to our support team with your batchId and error details

Changelog

This guide was last updated on October 21, 2025