> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Sumsub KYC Integration for Real-Time Verification Syncing

> Connect your Sumsub account to Corsa for real-time KYC/KYB verification syncing and automated compliance workflows.

Connect your [Sumsub](https://sumsub.com/) account to Corsa to keep KYC and KYB applicants, verification results, documents, and review outcomes in sync with your Corsa clients.

## Quick Start

To connect Sumsub to Corsa:

1. Create a Sumsub app token and copy the **API Token** and **API Secret Key**.
2. In Corsa, go to **Developers Hub → Integrations → Sumsub**.
3. Paste the Sumsub API credentials and save the integration.
4. In Corsa, open the Sumsub webhook configuration and copy the **Webhook URL** and **Webhook Secret Key**.
5. In Sumsub, create a webhook using that URL and secret key.
6. Enable the required applicant events in Sumsub.
7. Create or update a test applicant in Sumsub and confirm the client appears or updates in Corsa.

For the best matching experience, set Sumsub `externalUserId` to the stable customer ID you use in Corsa. Corsa stores it as the client `referenceId`.

## How It Works

1. **Secure Connection** - Add your Sumsub API token and secret key in Corsa. Credentials are encrypted and stored securely.
2. **Webhook Sync** - Sumsub sends applicant events to Corsa whenever an applicant is created, waits for action, moves into review, or receives a final decision.
3. **Client Matching** - Corsa links each Sumsub applicant to the matching Corsa client or creates a new client when no match exists.
4. **Verification Updates** - Corsa updates client status, verification checks, uploaded verification documents, and Sumsub review details.
5. **Automations** - Optional settings can create alerts for failed or action-required verifications and apply Sumsub risk labels as Corsa client tags.

## What Gets Synced

### Clients

Sumsub applicants are synced into Corsa as individual or corporate clients.

* Individual applicants become individual clients.
* Company applicants become corporate clients.
* The Sumsub `externalUserId` becomes the Corsa client `referenceId`.
* The Sumsub Applicant ID is stored on the client record.
* Deleted applicants are marked as inactive in Corsa.

### Verification Results

Corsa creates or updates a Sumsub verification record for each synced applicant.

Verification records include:

* Sumsub Applicant ID
* Sumsub review status and review answer
* Verification status in Corsa
* Review comments and reject labels
* Verification checks, such as identity, selfie, proof of residence, company, company documents, and company beneficiaries
* Links back to the applicant in the Sumsub dashboard

### Documents

Corsa imports supported verification documents from Sumsub and attaches them to the matching client verification.

Supported file types are `jpeg`, `jpg`, `png`, and `pdf`. Files larger than 20 MB are skipped.

### Corporate Members

For company applicants, Corsa can create or update corporate members from Sumsub beneficiary data. Individual beneficiary documents are attached when approved identity document images are available.

## Client Matching

When Corsa receives a Sumsub applicant:

1. Corsa first looks for a client with the same Sumsub Applicant ID.
2. If no client is found, Corsa looks for an existing client with the same email address and the same client type.
3. If no match exists, Corsa creates a new individual or corporate client.

Email matching is intentionally conservative. If multiple clients share the same email, Corsa does not auto-merge them.

## Status Mapping

| Sumsub Review State         | Corsa Client Status | Corsa Verification Status |
| --------------------------- | ------------------- | ------------------------- |
| `init`                      | Pending Documents   | Pending                   |
| `pending`                   | In Review           | Pending                   |
| `awaitingService` + `GREEN` | Waiting for Review  | Pending                   |
| `onHold`                    | Waiting for Review  | Pending                   |
| `awaitingUser`              | Pending Documents   | Requested                 |
| `completed` + `GREEN`       | Approved            | Approved                  |
| `completed` + `RED`         | Rejected            | Rejected                  |

The original Sumsub status and review answer are preserved on the verification record for auditability.

## Prerequisites

* A Sumsub account with permission to generate API credentials and configure webhooks.
* A Sumsub API token that can read applicants, required document-check status, applicant document metadata, and applicant document files.
* Owner access to the Corsa application.

## Setting Up the Sumsub Integration

### Step 1: Create API Credentials in Sumsub

1. Log in to your Sumsub account and navigate to **Dev space → App tokens**.
2. Click **Generate app token** and give it a descriptive name (e.g., "Corsa Integration").
3. Copy and save the **API Token** and **API Secret Key**.

<Warning>The secret key is only shown once when created. Save it securely.</Warning>

### Step 2: Configure in Corsa

1. Log in to Corsa.
2. Go to **Developers Hub → Integrations**.
3. Click **Configure** on the Sumsub card.
4. Enter the Sumsub credentials (API Token and Secret Key).
5. Save the integration.

### Step 3: Configure Automation Settings

* **Create alert on verification failure** - When a Sumsub verification is rejected or fails, Corsa automatically opens an alert on the corresponding client. You can set the priority of the alert (High, Medium, or Low).
* **Create alert when verification requires action** - When a Sumsub verification is placed on hold and needs manual review, Corsa automatically opens an alert on the corresponding client. You can set the priority of the alert (High, Medium, or Low).
* **Auto-tag risk labels in client profile** - Risk labels assigned in Sumsub (e.g. PEP, Sanction) are automatically applied as tags on the matching client profile in Corsa, keeping risk context in sync.

<Note>Alerts are created after a short intentional delay. If the client status changes before the alert is created, Corsa skips the alert.</Note>

### Step 4: Configure Webhook in Sumsub

After saving, Corsa generates a webhook configuration. Open the Sumsub integration card in Corsa and copy these values:

* **Webhook URL**
* **Webhook Secret Key**
* Required event list
* Applicant type: **All Types**
* Signature algorithm: **SHA256 (HMAC\_SHA256\_HEX)**

Then configure the webhook in your Sumsub dashboard:

1. Navigate to **Dev space → Webhooks → Webhook manager**.
2. Click **Create Webhook** and add a name (e.g., "Corsa Integration Webhook").
3. Paste the **webhook URL** from Corsa.
4. Set signature algorithm to **SHA256 (HMAC\_SHA256\_HEX)**.
5. Enter the **webhook secret key** from Corsa.
6. Select applicant types: **All types**.
7. Enable the following events: `applicantCreated`, `applicantPending`, `applicantAwaitingService`, `applicantOnHold`, `applicantAwaitingUser`, `applicantReviewed`, `applicantLevelChanged`.

### Step 5: Test the Integration

Create or update a test applicant in Sumsub. In Corsa, confirm that:

* A matching client is updated, or a new client is created.
* The client has the Sumsub Applicant ID attached.
* A Sumsub verification appears on the client.
* Verification checks and supported documents appear after Sumsub makes them available.

## Historical Verification Import

Corsa can refresh historical verification data for clients that already have a Sumsub Applicant ID.

To run a historical refresh:

1. Add the Sumsub Applicant ID to the client record in Corsa, or create the client with that Sumsub Applicant ID through the Corsa API.
2. Go to **Developers Hub → Integrations → Sumsub**.
3. Trigger a full sync.

The refresh re-fetches Sumsub applicant data, review status, verification checks, and supported documents for matching clients. It does not import every applicant from Sumsub unless those applicants are already linked to Corsa clients by Sumsub Applicant ID.

## API Access

Use the Corsa API when you need to pre-create clients, attach a Sumsub Applicant ID, or read synced verification data.

| Purpose                                                          | Endpoint                                                         |
| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
| Create or update an individual client with a Sumsub Applicant ID | `POST /v1/clients/individuals?upsert=true`                       |
| Create or update a corporate client with a Sumsub Applicant ID   | `POST /v1/clients/corporates?upsert=true`                        |
| Retrieve an individual client by Sumsub Applicant ID             | `GET /v1/clients/individuals/{applicantId}?integrationId=SUMSUB` |
| Retrieve a corporate client by Sumsub Applicant ID               | `GET /v1/clients/corporates/{applicantId}?integrationId=SUMSUB`  |
| Read Sumsub verification data for a client                       | `GET /v1/clients/{clientId}/verifications?provider=SUMSUB`       |

## Troubleshooting

| Issue                              | Resolution                                                                                                            |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Webhook events are not syncing     | Confirm the webhook URL, secret key, `HMAC_SHA256_HEX` signature algorithm, applicant type, and event list in Sumsub. |
| Historical data is not importing   | Confirm each Corsa client has the correct Sumsub Applicant ID before triggering full sync.                            |
| Duplicate clients were created     | Confirm Sumsub `externalUserId` and applicant email values match your intended Corsa client records.                  |
| Alert was not created              | Confirm the automation setting is enabled and that the client status did not change before the alert delay elapsed.   |
| Verification documents are missing | Confirm the applicant has supported document files in Sumsub. Files over 20 MB or unsupported file types are skipped. |

<Note>New clients from Sumsub do not need to be pre-created in Corsa. They will be created automatically when Corsa receives the first supported Sumsub applicant event.</Note>

***

Corsa offers native integrations with leading compliance, blockchain analytics, and custody providers. [See all integrations](/integrations) or [schedule a demo](https://calendly.com/michellelatzer/welcome-to-corsa) to see how Corsa fits into your stack.