> For the complete documentation index, see [llms.txt](https://docs.orangepill.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orangepill.cloud/orangepill-api/kyc/sumsub.md).

# Sumsub

## Prerequisites

Before Sumsub can be used as a KYC provider in Orangepill, you must complete the following setup steps:

#### **1. Identify the Realm Key (Source Key)**

In Orangepill, each **company** is associated with a **realm**, which acts as a logical grouping for identities and integrations. When a company is created:

* A **realm** is automatically created in Orangepill.
* A unique **realm key** (UUID) is generated and assigned to that realm.

This **realm key** will serve as the **source key** for integrating with Sumsub and must be used when creating related entities (e.g., webhooks, app tokens, applicants) within Sumsub.

> Example Realm Key:\
> `e69ea64e-64d1-4d64-8c5c-806923a537a8`

#### **2. Create a Webhook in Sumsub**

Configure a webhook in Sumsub to notify Orangepill about **applicant status changes**. Make sure to use the webhook type:

> **`applicantReviewed`**

This webhook is triggered whenever an applicant's review status changes (e.g., approved, rejected).

**Webhook URL Format:**

```
https://proxy.orangepill.cloud/v1/kycs/session/notify/sumsub/<realm-key>
```

After setting up the webhook:

* **Select the `applicantReviewed` type**.
* **Copy the Webhook Secret Key** — this will be used by Orangepill to verify the authenticity of incoming webhook requests via HMAC signature.
* **Assign the Realm Key as the Source Key** in Sumsub — this links the webhook to a specific realm and ensures only users/applicants within that context trigger notifications.

#### 3. Generate App Token and Secret Key

In Sumsub, generate an **App Token** scoped to the same realm (using the realm key as the source). This process returns:

* `app_token`: Used for authenticating API calls from Orangepill to Sumsub.
* `secret_key`: Used to sign requests.

This `app_token` and `secret_key` pair must also be stored alongside the realm’s configuration in Orangepill.

***

## Registering the Sumsub Provider in Orangepill

Once the necessary credentials have been collected, you can register Sumsub as a KYC provider within Orangepill using the internal API.

#### Example API Request

```bash
curl --location 'https://api.orangepill.cloud/v1/kycs' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "provider": "sumsub",
    "base_url": "https://api.sumsub.com",
    "credentials": {
        "app_token": "<APP_TOKEN>",
        "secret_key": "<SECRET_KEY>",
        "webhook_secret": "<WEBHOOK_SECRET>"
    },
    "data": {
        "allow_session_storage": true
    }
}'
```

#### Field Descriptions

| Field                        | Description                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `provider`                   | The name of the provider. Must be `"sumsub"`.                                 |
| `base_url`                   | Sumsub API base URL. Usually `https://api.sumsub.com`.                        |
| `credentials.app_token`      | Token issued by Sumsub to identify your application.                          |
| `credentials.secret_key`     | Used to sign and verify Sumsub requests.                                      |
| `credentials.webhook_secret` | Secret for verifying webhook payloads from Sumsub.                            |
| `data.allow_session_storage` | If true, allows Orangepill to store `applicantId` on the associated identity. |

**Successful Response:**

```
{
    "id": "<PROVIDER_ID>",
    "provider": "sumsub",
    "data": {
        "allow_session_storage": true
    },
    "baseUrl": "https://api.sumsub.com",
    "createdAt": 1752855581224,
    "deleted": false
}
```

***

## Retrieve a Registered KYC Provider

Once a KYC provider (e.g., Sumsub) has been registered in Orangepill, you can retrieve its configuration using the provider’s unique identifier.

#### API: Get KYC Provider by ID

**Request:**

```bash
curl --location 'https://api.orangepill.cloud/v1/kycs/<PROVIDER_ID>' \
--header 'x-api-key: <API_KEY>'
```

* Replace `<provider_id>` with the ID returned during provider registration.
* Replace `<API_KEY>` with a valid Orangepill API key.

***

**Successful Response:**

```json
{
  "id": "<PROVIDER_ID>",
  "provider": "sumsub",
  "data": {
    "allow_session_storage": true
  },
  "baseUrl": "https://api.sumsub.com",
  "createdAt": 1752512730707,
  "deleted": false
}
```

***

## Create a KYC Verification Session

Once the provider has been registered and configured, you can initiate a KYC verification session for a user by creating an **applicant** in Sumsub through Orangepill’s API.

Orangepill will generate a Sumsub applicant using the user’s **identity ID** (used as the external user ID), and return a session token that can be used to launch the Sumsub SDK or WebApp.

#### API: Create Sumsub KYC Session

**Endpoint:**

```
POST /v1/kycs/session/sumsub
```

**Request:**

```bash
curl --location 'https://api.orangepill.cloud/v1/kycs/session/sumsub' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "parameters": {
        "level_name": "basic-kyc-level",
        "external_user_id": "<IDENTITY_ID>"
    }
}'
```

#### Request Body Parameters

| Field              | Description                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `level_name`       | The verification level configured in your Sumsub dashboard (e.g., `basic-kyc-level`).                     |
| `external_user_id` | The ID of the identity in Orangepill. This will be mapped to Sumsub’s `externalUserId` for the applicant. |

**Successful Response:**

```json
{
    "id": "<APPLICANT_ID>",
    "externalUserId": "<IDENTITY_ID>",
    "sourceKey": "<REALM_KEY>",
    ...
}
```

***

## Upload Verification Files for an Applicant

Once a Sumsub applicant has been created, the next step is to upload the necessary verification files (e.g., selfies, ID front/back images) using Orangepill’s unified API.

This endpoint allows the platform to send document files to Sumsub on behalf of the user.

#### API: Upload Verification File

**Endpoint:**

```url
POST /v1/kycs/verification/sumsub/file
```

**Request:**

```bash
curl --location 'https://api.orangepill.cloud/v1/kycs/verification/sumsub/file' \
--header 'x-api-key: <API_KEY>' \
--form 'applicantId="687a4fe322f276e950dcc5fc"' \
--form 'idDocType="SELFIE"' \
--form 'idDocSubType="FRONT_SIDE"' \
--form 'country="RUS"' \
--form 'content=@"/selfie.png"' \
--form 'firstName="JOHN"' \
--form 'lastName="WICK"'
```

#### Request Form Parameters

| Field          | Description                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------- |
| `applicantId`  | The Sumsub applicant ID obtained from the session creation step.                            |
| `idDocType`    | Type of document being uploaded. Common values: `PASSPORT`, `ID_CARD`, `DRIVERS`, `SELFIE`. |
| `idDocSubType` | Document side or subcategory. E.g., `FRONT_SIDE`, `BACK_SIDE`, or leave blank for `SELFIE`. |
| `country`      | 3-letter ISO 3166-1 alpha-3 country code (e.g., `DEU` for Germany).                         |
| `content`      | The actual image or PDF file to upload. Must be a binary file (e.g., PNG, JPEG).            |
| `firstName`    | Applicant's first name (used by Sumsub to enrich data).                                     |
| `lastName`     | Applicant's last name (used by Sumsub to enrich data).                                      |

> ⚠️ The file size must comply with Sumsub’s upload restrictions (typically < 50MB per file).

#### Behavior

* This endpoint uploads the document to Sumsub on behalf of the applicant.
* Multiple documents can be uploaded using separate requests (e.g., front and back of ID card).
* If a required field is missing or the document is invalid, Sumsub will reject the upload and respond with an error.

**Successful Response:**

```json
{
    "idDocType": "SELFIE",
    "country": "RUS"
    "firstName": "JOHN",
    "lastName": "WICK"
}
```

***

## Submit Document Metadata Without File Upload

In some cases, it's necessary to send document-related information **without uploading a file**. This could include updating document details, enriching metadata, or triggering verification when documents are submitted through alternative channels.

Orangepill provides a dedicated endpoint to send **applicant metadata** to Sumsub, independent of file uploads.

#### API: Submit Verification Info

**Endpoint:**

```
bashCopyEditPOST /v1/kycs/verification/sumsub/info
```

**Request:**

```bash
bashCopyEditcurl --location 'https://api.orangepill.cloud/v1/kycs/verification/sumsub/info' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "applicantId": "6877fa681a4796e48f32b888",
    "idDocType": "PASSPORT",
    "idDocSubType": "FRONT_SIDE",
    "firstName": "PETER",
    "lastName": "SULLIVAN",
    "country": "ZAF",
    "placeOfBirth": "ZAF"
}'
```

#### Behavior

* This endpoint sends applicant metadata to Sumsub.
* It does **not** include any file content.
* Can be used before or after file uploads to keep data up to date.
* Useful for compliance workflows where document info is verified separately.