Sumsub KYC Connector overview

The Sumsub KYC Connector leverages Sumsub’s 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 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 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 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	• Profile data is not available for the Sumsub applicant
provider_data_invalid	• Sumsub applicant contains first or middle name but no last name • Profile data is incomplete (when birthplace country or town is provided but not both) • Extracted profile data failed validation
sumsub_client_error	• Sumsub API returned an error when fetching applicant data
sumsub_applicant_review_state_invalid	• Sumsub applicant review answer is not approved (GREEN) on the donor • Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)
provider_data_readiness_timeout_exceeded	• Max retries exceeded waiting for provider data to be ready
workflow_error	• Workflow was canceled • Workflow timed out • Workflow had an unrecoverable error
unknown_error	• Any unhandled error during the workflow

Address

Ingests address information by matching addresses from the Sumsub applicant against the user’s country and subdivision provided via the Create User endpoint. The ingestion follows a prioritized matching strategy:

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

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.
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 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) • Address country does not match the user’s declared address country • Extracted address data failed validation
operation_not_allowed	• Subdivision does not match user-declared subdivision (US residents only, state) • Subdivision updates are not allowed for the organization
sumsub_client_error	• Sumsub API returned an unrecoverable error
sumsub_applicant_review_state_invalid	• Sumsub applicant review answer is not approved (GREEN) on the donor • Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)
workflow_error	• Workflow was canceled • Workflow timed out • Workflow had an unrecoverable error
unknown_error	• Any unhandled error during the workflow

Identity

Ingests government-issued identity 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 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_readiness_timeout_exceeded	• Max retries exceeded waiting for provider data to be ready
provider_data_not_available	• No identity verification step found for the Sumsub applicant • No selfie verification step found for the Sumsub applicant
provider_data_invalid	• Sumsub’s identity verification step review answer is not approved (GREEN) • Sumsub’s selfie verification step review answer is not GREEN • Identity data extracted from Sumsub is incomplete (missing required fields) • Extracted identity data failed validation (e.g., user is under age)
provider_file_download_failed	• User has reached the maximum number of files allowed • Timeout waiting for file to be downloaded • Downloaded file status is invalid
dependent_process_failed	• Dependent profile process has failed
operation_not_allowed	• Current status of the identity process does not allow updates • User cannot submit identity due to incomplete declared information
sumsub_client_error	• Sumsub API returned an unrecoverable error
sumsub_applicant_review_state_invalid	• Sumsub applicant review answer is not approved (GREEN) on the donor • Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)
workflow_error	• Workflow was canceled • Workflow timed out • Workflow had an unrecoverable error
unknown_error	• Any unhandled error during the workflow

Proof-of-address

Ingests proof-of-address 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 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_readiness_timeout_exceeded	• Max retries exceeded waiting for provider data to be ready
provider_data_not_available	• No proof-of-address verification step found for the Sumsub applicant
provider_data_invalid	• Sumsub’s proof-of-address verification step review answer is not approved (GREEN) • Proof-of-address data extracted from Sumsub is incomplete (missing required fields) • Extracted proof-of-address data failed validation
provider_file_download_failed	• User has reached the maximum number of files allowed • Timeout waiting for file to be downloaded • Downloaded file status is invalid
dependent_process_failed	• Dependent profile process has failed • Dependent address process has failed
operation_not_allowed	• Current status of the proof-of-address process does not allow updates • User cannot submit proof-of-address due to incomplete declared information
sumsub_client_error	• Sumsub API returned an unrecoverable error
sumsub_applicant_review_state_invalid	• Sumsub applicant review answer is not approved (GREEN) on the donor • Sumsub applicant is in an unexpected review status (`init`, `onHold`, `awaitingUser`)
workflow_error	• Workflow was canceled • Workflow timed out • Workflow had an unrecoverable error
unknown_error	• Any unhandled error during the workflow

By default, Sumsub does not extract OCR data in sandbox (e.g., address details) from proof-of-address documents uploaded by the applicant. If you try to ingest proof-of-address of an applicant that has no OCR data extracted, the following error will surface:

{
  "proofOfAddress": {
    "status": "failed",
    "error": {
      "code": "provider_data_not_available",
      "message": "No idDoc matching proof-of-address verification step found in Sumsub applicant info",
      "step": "fetch-provider-data"
    }
  }
}

As a workaround, you can manually fill in the OCR data in the Sumsub dashboard for the applicant, which will allow the ingestion to succeed.

Core API

KYC Connector API

Market Pulse API

Widgets API

Topper API

Sumsub KYC Connector overview

Setup requirements

Supported processes

Profile

Address

Identity

Proof-of-address

​Setup requirements

​Supported processes

​Profile

​Address

​Identity

​Proof-of-address

Setup requirements

Supported processes

Profile

Address

Identity

Proof-of-address