Veriff KYC Connector overview

The Veriff KYC Connector integrates with Veriff’s verification platform to enable secure and compliant sharing of KYC data between your Veriff integration and Uphold’s platform.

Setup requirements

Before you can use the Veriff KYC Connector, you must have at least one Veriff integration set up in your Veriff Station dashboard, with the appropriate verification flows enabled. Refer to Veriff’s developer documentation for guidance on setting up integrations.

Getting started

Configuring your integrations on Uphold

Once you have your Veriff integrations ready, you need to register them with Uphold using the Set Veriff config endpoint. This is required before creating any ingestions. For each integration, you will need:

Integration name: A name of your choice to identify the integration.
API key and shared secret key: Found in your Veriff Station dashboard under the integration’s settings.

Uphold stores these credentials securely, so that when creating an ingestion you only need to reference the integration name and the session ID.

Selecting a session

A session represents a Veriff verification for a user. Only sessions in an approved state are accepted. The KYC processes that can be ingested depend on the verification flow and features enabled in your Veriff integration. For example:

A standard IDV session with document and selfie verification can be used to ingest profile, address, and identity processes.
A PoA session with address validation can be used to ingest address and proof-of-address processes.

Creating ingestions

To create an ingestion, you provide the session ID and integration name for each Veriff session you want to process. You can include both an IDV and a PoA session in a single ingestion.

POST /kyc-connector/veriff/ingestions

{
  "processes": [
    "profile",
    "address",
    "identity",
    "proof-of-address"
  ],
  "sessions": [
    {
      "processes": [
        "profile",
        "identity"
      ],
      "sessionId": "550e8400-e29b-41d4-a716-446655440000",
      "integrationName": "my-idv-integration"
    },
    {
      "processes": [
        "address",
        "proof-of-address"
      ],
      "sessionId": "661f9511-f30c-52e5-b827-557766551111",
      "integrationName": "my-poa-integration"
    }
  ]
}

Supported processes

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

Profile

Ingests profile information such as the user’s full name, date of birth, and citizenship. The source fields from Veriff used for this process are as follows:

fullName: Sourced from person.firstName and person.lastName.
birthdate: Sourced from person.dateOfBirth.
birthplace: Sourced from person.placeOfBirth. Only extracted when both the town and country are present in the Veriff verification; if either is missing, this field will not be populated.
primaryCitizenship: Sourced from person.nationality or person.citizenship.

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 Veriff verification • No IDV session provided
veriff_session_not_approved	• Veriff session is not in an approved state
provider_data_recheck_failed	• Verification data did not pass validation checks
provider_config_error	• Failed to fetch or parse the organization’s provider config • Integration referenced in session not found in provider config
veriff_client_error	• Veriff API returned an error when fetching verification data
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 Veriff verification against the user’s subdivision and country provided via the Create User endpoint. Address data can come from either an IDV or PoA Veriff session:

Address matching (PoA feature): If the PoA “address matching” feature is enabled for your integration in the Veriff platform, the user’s declared address is extracted directly from the matching result.
Person addresses fallback: Otherwise, the ingestion searches all addresses in the verification’s person data for one that matches the user’s declared country and/or subdivision, prioritizing a country + subdivision match over a country-only match.

When both session types are provided, the PoA address matching data always takes precedence over the IDV person addresses fallback.

If no compatible address is found through this 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 in the Veriff verification • No IDV or PoA session provided
veriff_session_not_approved	• Veriff session is not in an approved state
provider_data_recheck_failed	• Verification data did not pass validation checks
provider_config_error	• Failed to fetch or parse the organization’s provider config • Integration referenced in session not found in provider config
veriff_client_error	• Veriff API returned an unrecoverable error
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 a Veriff IDV session that includes both identity document verification and a selfie/biometric check. 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_not_available	• No person data found in Veriff verification • No IDV session provided
provider_data_invalid	• No document data found in Veriff verification
veriff_session_not_approved	• Veriff session is not in an approved state
provider_data_recheck_failed	• Verification data did not pass validation checks
provider_config_error	• Failed to fetch or parse the organization’s provider config • Integration referenced in session not found in provider config
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
veriff_client_error	• Veriff API returned an unrecoverable error
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 a PoA session. Veriff’s PoA verification must be enabled for your Veriff integration. The ingestion extracts the proof-of-address data using the following priority:

Address validation (PoA feature): If the PoA address validation feature is enabled for your integration in the Veriff platform, the address is extracted directly from the validation result.
Address matching (PoA feature): If the PoA address matching feature is enabled for your integration in the Veriff platform, the verified address is extracted directly from the matching result.

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_not_available	• No proof-of-address data found in the Veriff PoA session • No PoA session provided
veriff_session_not_approved	• Veriff session is not in an approved state
provider_data_recheck_failed	• Verification data did not pass validation checks
provider_config_error	• Failed to fetch or parse the organization’s provider config • Integration referenced in session not found in provider config
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
veriff_client_error	• Veriff API returned an unrecoverable error
workflow_error	• Workflow was canceled • Workflow timed out • Workflow had an unrecoverable error
unknown_error	• Any unhandled error during the workflow

Core API

KYC Connector API

Market Pulse API

Widgets API

Topper API

Veriff KYC Connector overview

Setup requirements

Getting started

Configuring your integrations on Uphold

Selecting a session

Creating ingestions

Supported processes

Profile

Address

Identity

Proof-of-address

​Setup requirements

​Getting started

​Configuring your integrations on Uphold

​Selecting a session

​Creating ingestions

​Supported processes

​Profile

​Address

​Identity

​Proof-of-address

Setup requirements

Getting started

Configuring your integrations on Uphold

Selecting a session

Creating ingestions

Supported processes

Profile

Address

Identity

Proof-of-address