> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.orangepill.cloud/orangepill-api/kyc/sumsub.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.