Purpose: Share and onboard Sumsub-verified applicants into the Reap platform without requiring re-verification, using either batch CSV upload or single-record synchronous ingestion.

When to Use This

Use this guide when you need to:

• Migrate applicants already verified in your Sumsub account to Reap
• Onboard pre-verified entities without triggering re-verification
• Bulk import a large set of applicants via CSV
• Share and onboard a single applicant in real time during onboarding flows
• Associate a card processor token with a newly onboarded entity

Overview

Sumsub KYC Sharing allows businesses that already perform KYC in their own Sumsub account to reuse those verifications when onboarding entities to Reap. Instead of re-verifying applicants, share tokens are generated from the donor Sumsub account and shared with Reap as the authorised recipient for onboarding.

Two ingestion modes are supported: a batch flow for sharing and onboarding large applicant lists via CSV upload, and a synchronous flow for sharing and onboarding one applicant at a time with an immediate processing result. This avoids duplicate verification work, reduces onboarding friction, and enables real-time entity creation during user signup.

⚠️

BIN-sponsored clients follow a modified workflow. The cardProcessorPublicToken must be included in both bulk CSV uploads and synchronous ingestion requests.

Prerequisites

1. A signed Sumsub Reusable KYC Agreement authorizing the donor company as the donor and Reap as the recipient
2. Reap added as an authorised recipient in the donor Sumsub account using the token provided by the Reap Account Manager
3. A valid Reap API key is required to authenticate all KYC ingestion requests
4. Access to the Sumsub dashboard to filter, export, and generate share tokens for applicants

Key Concepts

Donor and Recipient

• Donor: The Sumsub account that performed the original verification (the donor business)
• Recipient: The Sumsub account authorized to consume the shared verification (Reap)

Share Token

• Single-use token representing a shareable applicant verification
• Expires 1,200 seconds (20 minutes) after generation
• Must be shared with Reap before expiry

External ID

• Unique identifier for the entity within the donor system
• Used to correlate applicants between the donor platform and Reap

Flow Overview

1. Complete one-time setup with Sumsub and Reap
2. Export the applicant list from the Sumsub dashboard
3. Generate share tokens using the kyc-share-token CLI
4. Share and onboard applicants via either:
   • POST /entity/kyc/import/batch for bulk CSV uploads
   • POST /entity/kyc/import/sync for single-record synchronous ingestion
5. Monitor batch progress via GET /entity/kyc/import/batch/batchId or handle synchronous responses inline

API Summary

Bulk Applicant Migration via CSV

Step 1: Prepare the Applicant List

Filter and export the list of applicants to be shared with Reap from the Sumsub dashboard.

Required CSV Columns

File Constraints

Step 2: Generate Share Tokens

Use the open-source Reap CLI tool to generate share tokens for each applicant in the exported CSV.

Tool

kyc-share-token — Generates share tokens from Sumsub applicant IDs with automatic rate limiting, retry logic, and resume functionality.

Refer to the repository documentation for installation and usage instructions.

Input and Output

ℹ️

Share tokens are single-use and expire after 1,200 seconds (20 minutes).

Step 3: Batch Share and Onboard Applicants

Upload the generated CSV to share and onboard applicants in bulk.

Call the KYC Batch Import Endpoint

Use POST /entity/kyc/import/batch to upload a CSV containing externalId and shareToken pairs for asynchronous processing.

ℹ️

Partial failures are supported. Valid records continue processing even if others fail when a batch contains multiple records. A completed batch may contain a mix of successful and failed submissions, and successful records still return usable external IDs regardless of failures elsewhere in the same batch.

Sample Request (cURL)

curl --request POST \
  --url https://sandbox-compliance.api.reap.global/entity/kyc/import/batch \
  --header 'Accept: application/json' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-reap-api-key: ********' \
  --form '[email protected]'

Key Input

⚠️

For BIN sponsorship clients: include an additional cardProcessorPublicToken column in the uploaded CSV alongside externalId and shareToken. This column is not required for non-BIN-sponsorship clients. The value in this column must be the 9-digit numeric public token for the card processor account and not the 16-digit tokenised PAN.

Sample Response

{
  "batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending",
  "totalRecords": 0,
  "message": "string",
  "createdAt": "2026-04-28T02:54:28.577Z"
}

Key Output

ℹ️

Processing Time

• Uploads begin processing within ~10 minutes

• Typically completes in 2–10 minutes per 1,000 records Retry Safety (Idempotency)

• Duplicate uploads with the same idempotency key are safely ignored

• Failed uploads can be retried without creating duplicates

Step 4: Monitor Batch Status

Poll the batch status endpoint to track progress, retrieve final completion state, and inspect per-record errors for any records that permanently failed within the batch.

Call the KYC Batch Status Endpoint

Use GET /entity/kyc/import/batch/batchId to retrieve the current state of a previously submitted batch share and onboard job.

Sample Request (cURL)

curl --request GET \
  --url https://sandbox-compliance.api.reap.global/entity/kyc/import/batch/batchId \
  --header 'Accept: application/json' \
  --header 'x-reap-api-key: ********'

Key Input

Sample Responses

{
  "batchId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "COMPLETED",
  "totalRecords": 10,
  "processedRecords": 10,
  "failedRecords": 0,
  "createdAt": "2026-04-16T00:00:00.000Z",
  "updatedAt": "2026-04-16T00:10:00.000Z",
  "startedAt": "2026-04-16T00:01:00.000Z",
  "completedAt": "2026-04-16T00:10:00.000Z",
  "summary": {
    "successfulRecords": 10,
    "errors": []
  }
}

{
  "batchId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "COMPLETED",
  "totalRecords": 10,
  "processedRecords": 10,
  "failedRecords": 2,
  "createdAt": "2026-04-16T00:00:00.000Z",
  "updatedAt": "2026-04-16T00:10:00.000Z",
  "startedAt": "2026-04-16T00:01:00.000Z",
  "completedAt": "2026-04-16T00:10:00.000Z",
  "summary": {
    "successfulRecords": 8,
    "errors": [
      {
        "rowNumber": 3,
        "error": "Share token has already been used and cannot be reused.",
        "errorDetail": {
          "category": "TOKEN_ALREADY_USED",
          "message": "Share token has already been used and cannot be reused.",
          "retryable": false
        },
        "entityData": {
          "externalId": "ext-123",
          "shareToken": "share-token-abc"
        }
      },
      {
        "rowNumber": 7,
        "error": "Card processor public token is already assigned to a different entity",
        "errorDetail": {
          "category": "CARD_PROCESSOR_TOKEN_INVALID",
          "message": "Card processor public token is already assigned to a different entity",
          "retryable": false
        },
        "entityData": {
          "externalId": "ext-456",
          "shareToken": "share-token-def",
          "cardProcessorPublicToken": "tok_a|tok_duplicate123"
        }
      }
    ]
  }
}

{
  "batchId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "in_progress",
  "totalRecords": 10,
  "processedRecords": 7,
  "failedRecords": 0,
  "createdAt": "2026-04-16T00:00:00.000Z",
  "updatedAt": "2026-04-16T00:05:00.000Z",
  "startedAt": "2026-04-16T00:01:00.000Z",
  "summary": {
    "successfulRecords": 7,
    "errors": []
  }
}

Key Output

Real-Time Single Applicant Sharing and Onboarding

Step 1: Sync Share and Onboard a Single Applicant

Share and onboard a single applicant synchronously and receive the processing result immediately. Suitable for real-time onboarding flows.

Call the KYC Sync Import Endpoint

Use POST /entity/kyc/import/sync to share one Sumsub share token and onboard the entity. The request is processed immediately and the outcome is returned in the response.

Sample Request (cURL)

curl --request POST \
     --url https://sandbox-compliance.api.reap.global/entity/kyc/import/sync \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "externalId": "ef88fd57-26cf-415d-a112-941732c55350",
  "shareToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "cardProcessorPublicToken": "tok_abc123"
}
'

Key Input

⚠️

For BIN sponsorship clients only: cardProcessorPublicToken is mandatory. For all other clients, this field is optional and only required when associating the entity with a card processor account at ingestion time.

Sample Response

{
  "externalId": "ef88fd57-26cf-415d-a112-941732c55350",
  "status": "completed",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Key Output

ℹ️

Clients must refer to the returned error codes and error details on the endpoint page to determine the exact failure reason when a synchronous request fails. Use these details to decide on the next step.

Scenarios

Scenario: Bulk Migration of Existing Users

• Export applicants from Sumsub
• Generate share tokens via kyc-share-token
• Upload via POST /entity/kyc/import/batch
• Poll GET /entity/kyc/import/batch/batchId to confirm completion and review any per-record errors

Scenario: Real-Time Onboarding

• Generate a share token for a single applicant
• Call POST /entity/kyc/import/sync with the token
• Use the response to continue the onboarding flow inline

Scenario: Onboarding with Card Issuance

• Call POST /entity/kyc/import/sync
• Include cardProcessorPublicToken to associate the entity with a card processor account at ingestion time

Common Errors

TL;DR

• Sign the Sumsub Reusable KYC Agreement and add Reap as a recipient
• Export applicants and generate share tokens via the kyc-share-token CLI
• Use POST /entity/kyc/import/batch for bulk CSV sharing and onboarding
• Use POST /entity/kyc/import/sync for single-record real-time sharing and onboarding (3 rps per business)
• Poll GET /entity/kyc/import/batch/batchId to track batch progress and review per-record errors
• Share tokens are single-use and expire after 20 minutes

Support

📘

Contact your Reap Implementation Manager for any setup, sharing, or onboarding issues.