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

# Sumsub KYC Connector overview

> Use Sumsub Reusable KYC with the Uphold KYC Connector to share verifications between your Sumsub account and Uphold. Includes setup and configuration.

The Sumsub KYC Connector leverages [Sumsub's Reusable KYC](https://docs.sumsub.com/docs/reusable-kyc) feature to enable secure and compliant sharing of KYC data between your Sumsub account and Uphold's platform (using Uphold's Sumsub account).

## Setup requirements

Before you can use the Sumsub KYC Connector, both the **donor** (your Sumsub account where users complete verification) and the **recipient** (Uphold's Sumsub account) must be properly configured in Sumsub's dashboard to enable Reusable KYC data sharing.

Please reach out to your Uphold account manager to help coordinate the setup with you.

Once the setup is complete, sharing happens via a [share token](https://docs.sumsub.com/reference/generate-share-token) that you must generate for a given applicant. Uphold uses this token to copy the applicant's KYC data and documents.

## Supported processes

The Sumsub KYC Connector supports ingestion of the following KYC processes. Each process has specific considerations you should be aware of:

### Profile

Ingests [profile](../../core-api/kyc/introduction.mdx#kyc-processes) information such as the user's full name, date of birth, place of birth, and citizenship.

The source fields from Sumsub used for this process are as follows:

* `fullName`: Sourced from `fixedInfo.firstName`, `fixedInfo.middleName`, and `fixedInfo.lastName`. Falls back to the same fields on `info` if `fixedInfo` is not available.
* `birthdate`: Sourced from `fixedInfo.dob` or `info.dob`.
* `birthplace`: Sourced from `fixedInfo.countryOfBirth` for the country and `fixedInfo.placeOfBirth` or `info.stateOfBirth` for the town. Falls back to the same fields on `info` if `fixedInfo` is not available.
* `primaryCitizenship`: Sourced from `fixedInfo.nationality` or `info.nationality`.

Please check the [`ingestion.result.profile`](./get-ingestion#response-ingestion-result-profile) field in the specification for more details. Furthermore, here's a breakdown of errors that can happen for this process:

| Error Code                                                               | Scenarios                                                                                                                                                                                                      |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| provider\_<wbr />data\_<wbr />not\_<wbr />available                      | • Profile data is not available for the Sumsub applicant                                                                                                                                                       |
| provider\_<wbr />data\_<wbr />invalid                                    | • Sumsub applicant contains first or middle name but no last name<br />• Profile data is incomplete (when birthplace country or town is provided but not both)<br />• Extracted profile data failed validation |
| sumsub\_<wbr />client\_<wbr />error                                      | • Sumsub API returned an error when fetching applicant data                                                                                                                                                    |
| sumsub\_<wbr />applicant\_<wbr />review\_<wbr />state\_<wbr />invalid    | • Sumsub applicant review answer is not approved (GREEN) on the donor<br />• Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)                                             |
| provider\_<wbr />data\_<wbr />readiness\_<wbr />timeout\_<wbr />exceeded | • Max retries exceeded waiting for provider data to be ready                                                                                                                                                   |
| workflow\_<wbr />error                                                   | • Workflow was canceled<br />• Workflow timed out<br />• Workflow had an unrecoverable error                                                                                                                   |
| unknown\_<wbr />error                                                    | • Any unhandled error during the workflow                                                                                                                                                                      |

### Address

Ingests [address](../../core-api/kyc/introduction.mdx#kyc-processes) information by matching addresses from the Sumsub applicant against the user's country and subdivision provided via the [Create User](../../core-api/users/create-user.mdx#body-country) endpoint.

The ingestion follows a **prioritized matching** strategy:

1. **Declared addresses**: If the applicant has `fixedInfo.addresses` (declared addresses), these are the only only addresses added to the prioritized list (step 2 and 3 are skipped).
2. **Address from verification step**: If the applicant has completed a **Proof of address** verification step with a `GREEN` (approved) review result, the address from the associated document is added to the prioritized list.
3. **All other applicant addresses**: All other addresses from the applicant's `info.addresses` are added to the prioritized list with addresses sourced from `proofOfAddress` documents prioritized over other sources.

Then, the ingestion attempts to find a compatible address using the following matching criteria in order:

1. **Country and subdivision match**: From the prioritized list, the ingestion looks for an address that matches both the user's existing subdivision and country in Uphold.
2. **Country-only match**: If no exact match is found and either the user's existing address or the Sumsub address has an empty subdivision, the ingestion will match by country only.

If no compatible address is found through this matching process, the address ingestion will fail with a `provider_data_not_available` error.

Please check the [`ingestion.result.address`](./get-ingestion#response-ingestion-result-address) field in the specification for more details. Furthermore, here's a breakdown of errors that can happen for this process:

| Error Code                                                            | Scenarios                                                                                                                                                                         |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| provider\_data\_not\_available                                        | • No address data found for the Sumsub applicant                                                                                                                                  |
| provider\_data\_invalid                                               | • Address data is incomplete (missing required fields)<br />• Address country does not match the user's declared address country <br />• Extracted address data failed validation |
| operation\_not\_allowed                                               | • Subdivision does not match user-declared subdivision (US residents only, state)<br />• Subdivision updates are not allowed for the organization                                 |
| sumsub\_<wbr />client\_<wbr />error                                   | • Sumsub API returned an unrecoverable error                                                                                                                                      |
| sumsub\_<wbr />applicant\_<wbr />review\_<wbr />state\_<wbr />invalid | • Sumsub applicant review answer is not approved (GREEN) on the donor<br />• Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)                |
| workflow\_<wbr />error                                                | • Workflow was canceled<br />• Workflow timed out<br />• Workflow had an unrecoverable error                                                                                      |
| unknown\_<wbr />error                                                 | • Any unhandled error during the workflow                                                                                                                                         |

### Identity

Ingests government-issued [identity](../../core-api/kyc/introduction.mdx#kyc-processes) data, including document type, number, issuing country, expiration date, and biographic information.

This process requires that the Sumsub verification level completed by the applicant includes both **Identity document** and **Selfie** verification steps.

The exact settings for these steps (e.g., document types allowed) should match Uphold's KYC compliance requirements. If the applicant has completed both steps but the settings do not align with Uphold's requirements, the ingestion for this process will fail. Please consult with your Account Manager to ensure proper configuration.

Please check the [`ingestion.result.identity`](./get-ingestion#response-ingestion-result-identity) field in the specification for more details. Furthermore, here's a breakdown of errors that can happen for this process:

<div class="kyc-connector-errors-table">
  | Error Code                                                               | Scenarios                                                                                                                                                                                                                                                                                                     |
  | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | provider\_<wbr />data\_<wbr />readiness\_<wbr />timeout\_<wbr />exceeded | • Max retries exceeded waiting for provider data to be ready                                                                                                                                                                                                                                                  |
  | provider\_<wbr />data\_<wbr />not\_<wbr />available                      | • No identity verification step found for the Sumsub applicant<br />• No selfie verification step found for the Sumsub applicant                                                                                                                                                                              |
  | provider\_<wbr />data\_<wbr />invalid                                    | • Sumsub's identity verification step review answer is not approved (GREEN)<br />• Sumsub's selfie verification step review answer is not GREEN<br />• Identity data extracted from Sumsub is incomplete (missing required fields)<br />• Extracted identity data failed validation (e.g., user is under age) |
  | provider\_<wbr />file\_<wbr />download\_<wbr />failed                    | • User has reached the maximum number of files allowed<br />• Timeout waiting for file to be downloaded<br />• Downloaded file status is invalid                                                                                                                                                              |
  | dependent\_<wbr />process\_<wbr />failed                                 | • Dependent profile process has failed                                                                                                                                                                                                                                                                        |
  | operation\_<wbr />not\_<wbr />allowed                                    | • Current status of the identity process does not allow updates<br />• User cannot submit identity due to incomplete declared information                                                                                                                                                                     |
  | sumsub\_<wbr />client\_<wbr />error                                      | • Sumsub API returned an unrecoverable error                                                                                                                                                                                                                                                                  |
  | sumsub\_<wbr />applicant\_<wbr />review\_<wbr />state\_<wbr />invalid    | • Sumsub applicant review answer is not approved (GREEN) on the donor<br />• Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)                                                                                                                                            |
  | workflow\_<wbr />error                                                   | • Workflow was canceled<br />• Workflow timed out<br />• Workflow had an unrecoverable error                                                                                                                                                                                                                  |
  | unknown\_<wbr />error                                                    | • Any unhandled error during the workflow                                                                                                                                                                                                                                                                     |
</div>

### Proof-of-address

Ingests [proof-of-address](../../core-api/kyc/introduction.mdx#kyc-processes) documentation, such as utility bills, bank statements, or government correspondence.

This process requires that the Sumsub verification level completed by the applicant includes a **Proof of address** verification step.

The exact settings for this step (e.g., document types allowed) should match Uphold's KYC compliance requirements. If the applicant has completed a step but the settings do not align with Uphold's requirements, the ingestion for this process will fail. Please consult with your Account Manager to ensure proper configuration.

Please check the [`ingestion.result.proofOfAddress`](./get-ingestion#response-ingestion-result-address) field in the specification for more details. Furthermore, here's a breakdown of errors that can happen for this process:

<div class="kyc-connector-errors-table">
  | Error Code                                                               | Scenarios                                                                                                                                                                                                                               |
  | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | provider\_<wbr />data\_<wbr />readiness\_<wbr />timeout\_<wbr />exceeded | • Max retries exceeded waiting for provider data to be ready                                                                                                                                                                            |
  | provider\_<wbr />data\_<wbr />not\_<wbr />available                      | • No proof-of-address verification step found for the Sumsub applicant                                                                                                                                                                  |
  | provider\_<wbr />data\_<wbr />invalid                                    | • Sumsub's proof-of-address verification step review answer is not approved (GREEN)<br />• Proof-of-address data extracted from Sumsub is incomplete (missing required fields)<br />• Extracted proof-of-address data failed validation |
  | provider\_<wbr />file\_<wbr />download\_<wbr />failed                    | • User has reached the maximum number of files allowed<br />• Timeout waiting for file to be downloaded<br />• Downloaded file status is invalid                                                                                        |
  | dependent\_<wbr />process\_<wbr />failed                                 | • Dependent profile process has failed<br />• Dependent address process has failed                                                                                                                                                      |
  | operation\_<wbr />not\_<wbr />allowed                                    | • Current status of the proof-of-address process does not allow updates<br />• User cannot submit proof-of-address due to incomplete declared information                                                                               |
  | sumsub\_<wbr />client\_<wbr />error                                      | • Sumsub API returned an unrecoverable error                                                                                                                                                                                            |
  | sumsub\_<wbr />applicant\_<wbr />review\_<wbr />state\_<wbr />invalid    | • Sumsub applicant review answer is not approved (GREEN) on the donor<br />• Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)                                                                      |
  | workflow\_<wbr />error                                                   | • Workflow was canceled<br />• Workflow timed out<br />• Workflow had an unrecoverable error                                                                                                                                            |
  | unknown\_<wbr />error                                                    | • Any unhandled error during the workflow                                                                                                                                                                                               |
</div>