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

# Veriff KYC Connector overview

> Use the Uphold KYC Connector with Veriff's verification platform to share KYC data between your Veriff Station integration and Uphold's KYC processes.

The Veriff KYC Connector integrates with [Veriff's verification platform](https://www.veriff.com/) 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](https://station.veriff.com/integrations), with the appropriate verification flows enabled. Refer to [Veriff's developer documentation](https://devdocs.veriff.com/) 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](./set-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](https://station.veriff.com/integrations) 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](./create-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.

```json POST /kyc-connector/veriff/ingestions theme={null}
{
  "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](../../core-api/kyc/introduction.mdx#kyc-processes) 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`](./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 Veriff verification<br />• No IDV session provided                                          |
| veriff\_<wbr />session\_<wbr />not\_<wbr />approved  | • Veriff session is not in an approved state                                                                                        |
| provider\_<wbr />data\_<wbr />recheck\_<wbr />failed | • Verification data did not pass validation checks                                                                                  |
| provider\_<wbr />config\_<wbr />error                | • Failed to fetch or parse the organization's provider config<br />• Integration referenced in session not found in provider config |
| veriff\_<wbr />client\_<wbr />error                  | • Veriff API returned an error when fetching verification data                                                                      |
| 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 Veriff verification against the user's subdivision and country provided via the [Create User](../../core-api/users/create-user.mdx#body-country) endpoint.

Address data can come from **either an IDV or PoA Veriff session**:

1. **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.
2. **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.

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

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`](./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\_<wbr />data\_<wbr />not\_<wbr />available  | • No address data found in the Veriff verification<br />• No IDV or PoA session provided                                            |
| veriff\_<wbr />session\_<wbr />not\_<wbr />approved  | • Veriff session is not in an approved state                                                                                        |
| provider\_<wbr />data\_<wbr />recheck\_<wbr />failed | • Verification data did not pass validation checks                                                                                  |
| provider\_<wbr />config\_<wbr />error                | • Failed to fetch or parse the organization's provider config<br />• Integration referenced in session not found in provider config |
| veriff\_<wbr />client\_<wbr />error                  | • Veriff API returned an unrecoverable error                                                                                        |
| 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 a Veriff IDV session** that includes both identity document verification and a selfie/biometric check.

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 />not\_<wbr />available   | • No person data found in Veriff verification<br />• No IDV session provided                                                                     |
  | provider\_<wbr />data\_<wbr />invalid                 | • No document data found in Veriff verification                                                                                                  |
  | veriff\_<wbr />session\_<wbr />not\_<wbr />approved   | • Veriff session is not in an approved state                                                                                                     |
  | provider\_<wbr />data\_<wbr />recheck\_<wbr />failed  | • Verification data did not pass validation checks                                                                                               |
  | provider\_<wbr />config\_<wbr />error                 | • Failed to fetch or parse the organization's provider config<br />• Integration referenced in session not found in provider config              |
  | 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        |
  | veriff\_<wbr />client\_<wbr />error                   | • Veriff API returned an unrecoverable error                                                                                                     |
  | 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 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:

1. **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.
2. **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`](./get-ingestion#response-ingestion-result-proofOfAddress) 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 />not\_<wbr />available   | • No proof-of-address data found in the Veriff PoA session<br />• No PoA session provided                                                                 |
  | veriff\_<wbr />session\_<wbr />not\_<wbr />approved   | • Veriff session is not in an approved state                                                                                                              |
  | provider\_<wbr />data\_<wbr />recheck\_<wbr />failed  | • Verification data did not pass validation checks                                                                                                        |
  | provider\_<wbr />config\_<wbr />error                 | • Failed to fetch or parse the organization's provider config<br />• Integration referenced in session not found in provider config                       |
  | 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 |
  | veriff\_<wbr />client\_<wbr />error                   | • Veriff API returned an unrecoverable error                                                                                                              |
  | 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>