📘  
**Note**:  
To utilize RiskOS™ your DocV Android SDK integration must be on version 5 (v5) or later.

## Before you start  
Make sure you have the following:

Configure a DocV workflow and decision logic in [RiskOS™ DocV setup](https://help.socure.com/riskos/docs/docv-riskos-setup#/). The SDK cannot generate a transaction token until DocV is set up in your workflow.

Get a valid API key from the [Developer Workbench > API Keys](https://riskos.socure.com/developers/api-keys) page in RiskOS™.

Get a valid SDK key from the [Developer Workbench > SDK Keys](https://help.socure.com/riskos/docs/integration-guide-authentication#/) page in RiskOS™.

(Optional) Add your IP address to the [allowlist](https://help.socure.com/riskos/docs/ip-filtering#/) in RiskOS™.

### Android SDK integration notes  
The DocV SDK is compiled with the following:

- `compileSdkVersion: 36`
- `Java: 17`

#### Upgrading to Android DocV SDK v5.4.3 or later  
Starting with v5.4.3, the Socure SDK uses TensorFlow Lite 1.4.1, which supports the following CPU architectures:

- arm64-v8a
- armeabi-v7a

If you want to use the newer TensorFlow Lite 2.1.1 with SDK v5.4.3 or later, add a custom Gradle configuration:

```kotlin
configurations.configureEach {
    resolutionStrategy {
        force 'com.google.ai.edge.litert:litert:2.1.1'
    }
}
```

#### Upgrading to Android DocV SDK v5.4.0 or later  
This version is required to use **Kotlin Version 2.1.0 or later**. This is required to support the latest language features and library dependencies utilized in this version.

When upgrading to the **Android DocV v5.4.0 SDK or later**, you must also update the **Digital Intelligence SDK** to at least **v4.8.0**.

The Socure SDK uses TensorFlow Lite 2.1.0 in versions 5.4.0 through 5.4.2:

```kotlin
implementation 'com.google.ai.edge.litert:litert:2.1.0'
```

These versions support only the following CPU architectures:

- arm64-v8a
- x86_64

If your application must also support `armeabi-v7a`, you can force TensorFlow LiteRT version 1.4.1:

```kotlin
configurations.configureEach {
    resolutionStrategy {
        force 'com.google.ai.edge.litert:litert:1.4.1'
    }
}
```

#### Using the Digital Intelligence SDK independently  
If your application integrates the Digital Intelligence SDK **outside of DocV** (for example, for standalone device capture or validation), you must install the Digital Intelligence SDK **alongside DocV** to avoid runtime errors.

#### 16KB page support  
Beginning with Android DocV SDK v5.1.1, support for **16KB memory pages** is included.

> 📘  
> **Note:**  
> This feature requires **Android Gradle Plugin (AGP) v8.5.1 or higher**.  
> AGP 8.5.1 also requires **Gradle v8.7 or higher**.

## Step 1: Generate a transaction token and configure the Capture App  
To initiate the verification process, generate a transaction token (`docvTransactionToken`) by calling the Evaluation endpoint. We strongly recommend that customers generate this token via a server-to-server API call and then pass it to the DocV SDK to ensure the security of their API key and any data they send to Socure.

### Call the Evaluation endpoint  
1. From your backend, make a `POST` request to the `/api/evaluation` endpoint specifying the following information in the `config` object:

| Parameter | Required | Description |
| --- | --- | --- |
| `language` | Optional | Determines the [language package](https://help.socure.com/riskos/docs/language-options#/) for the UI text on the Capture App.<br>**Note**: Socure can quickly add support for any new language requirement that is not listed above. For more information, contact [support@socure.com](mailto:support@socure.com). |
| `use_case_key` | Optional | Deploys a customized Capture App flow on a per-transaction basis. Replace the `customer_use_case_key` value with the name of the flow you created in [RiskOS™](https://help.socure.com/riskos/docs/capture-app#/).<br>- If this field is empty, the Capture App will use the flow marked as **Default** in RiskOS™.<br>- If the value provided is incorrect, the SDK will return an `Invalid Request` error. |

Sample API call: The Evaluation endpoint

```curl
curl --location 'https://riskos.socure.com/api/evaluation' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'X-API-Version: 2025-01-01.orion' \
  --data-raw '{
    "id": "onb-12345",
    "workflow": "consumer_onboarding",
    "timestamp": "2025-01-08T14:57:42.089Z",
    "data": {
      "individual": {
        "id": "9876543",
        "given_name": "John",
        "family_name": "Doe",
        "national_id": "000-10-0007",
        "date_of_birth": "2002-07-28",
        "email": "johndoe@gmail.com",
        "phone_number": "+447767198341",
        "docv": {
          "config": {
            "use_case_key": "customer_use_case_key",
            ...
          }
        },
        "address": {
          "line_1": "Address Line 1",
          "locality": "New York City",
          "major_admin_division": "NY",
          "country": "US",
          "postal_code": "12345"
        }
      }
    }
  }'
```

> 📘  
> **Note**:  
> We recommend including as much consumer PII in the body of the request as possible to return the most accurate results.

2. When you receive the API response, collect the `docvTransactionToken`. This value is required to initialize the DocV Android SDK.

Sample API response: The Evaluation endpoint

```json
{
  "id": "Test-API-1",
  "workflow": "sc_onboarding",
  "workflow_id": "a8dff53b-74c1-411f-a43d-9597ae60e5ae",
  "workflow_version": "3.2.0",
  "eval_source": "API",
  "eval_id": "500c6b88-9f5c-4d62-9422-163a59a343fe",
  "eval_start_time": "2025-01-08T14:57:42.08985Z",
  "eval_end_time": "0001-01-01T00:00:00Z",
  "decision": "REVIEW",
  "decision_at": "2025-01-08T14:57:43.223321Z",
  "status": "ON_HOLD",
  "sub_status": "",
  "tags": null,
  "notes": "",
  "review_queues": [
    "Default Queue"
  ],
  "data_enrichments": [
    {
      "enrichment_name": "SocureDocRequest",
      "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
      "enrichment_provider": "SocureDocRequest",
      "status_code": 200,
      "request": {
        "city": "New York City",
        "country": "US",
        "dob": "2002-07-28",
        "firstName": "John",
        "mobileNumber": "+1234567891",
        "physicalAddress": "Address Line 1",
        "state": "NY",
        "surName": "Doe",
        "zip": "12345"
      },
      "response": {
        "data": {
          "docvTransactionToken": "70c6a4bc-f646-4c6a-94c1-9cd428e356ef",
          "eventId": "70c6a4bc-f646-4c6a-94c1-9cd428e356ef",
          "qrcode": "data:image/png;base64,iVBO......K5CYII=",
          "url": "https://verify.socure.com/#/dv/70c6a4bc-f646-4c6a-94c1-9cd428e356ef"
        },
        "referenceId": "aacdc975-0eb8-428d-9954-b42aab67f85f"
      },
      "is_source_cache": false,
      "total_attempts": 1
    }
  ],
  "eval_status": "evaluation_paused"
}
```

## Step 2: Add the DocV Android SDK  
To add the DocV SDK to your application, include the Socure DocV SDK Maven repository in your `build.gradle` file at the end of the `allprojects > repositories` section:

```kotlin
allprojects {
    repositories {
        ...
        maven { url 'https://sdk.socure.com' }
    }
}
```

In your module level `build.gradle` file, add the following Socure DocV SDK dependency and replace `x.y.z` with the DocV Android SDK version number (for example: `5.4.5`):

```kotlin
dependencies {
    implementation 'com.socure.android:docv-capture:5.4.7'
}
```

### Camera and file permissions  
The DocV SDK requires camera and file permission to capture identity documents. Upon the first invocation of the SDK, your app will request camera and file permission from the user.

> 📘  
> **Note**:  
> We recommend you check for camera and file permissions before calling the Socure DocV SDK's launch API.

Ensure that your app manifest has been set up properly to request the following required permissions:

```kotlin
<uses-feature android:name="android.hardware.camera" />

<!-- Declare permissions -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

### Initialize and launch the SDK  
To enable the DocV SDK functionality, add the following code to your app:

```kotlin
class Activity : AppCompatActivity() {

private lateinit var startForResult: ActivityResultLauncher<Intent>

override fun onCreate(savedInstanceState: Bundle?) {
        ...

startForResult = registerForActivityResult(
            ActivityResultContracts.StartActivityForResult()
        ) { result: ActivityResult ->
            result.data?.let { data ->
                SocureSdk.getResult(data) { sdkResult ->
                    Log.d(TAG, "onResult called: $sdkResult")

if (sdkResult is SocureDocVSuccess) {
                        Log.d(
                            TAG,
                            "success: ${sdkResult.deviceSessionToken}"
                        )
                    } else {
                        val error = sdkResult as? SocureDocVFailure
                        Log.d(
                            TAG,
                            "error: ${error?.deviceSessionToken}, " +
                            "${error?.error}"
                        )
                    }
                }
            }
        }

// Launch the SDK using the intent
        startForResult.launch(
            SocureSdk.getIntent(
                context,
                SocureDocVContext(
                    docvTransactionToken,
                    SDKKey,
                    useSocureGov
                )
            )
        )
    }
}
```

#### `startForResult.launch` function parameters  
The following table lists the arguments passed to the `startForResult.launch` function through `SocureSdk.getIntent`:

| Parameter | Type | Description |
| --- | --- | --- |
| `docVTransactionToken` | String | The transaction token retrieved from the API response of the `` endpoint. Required to initiate the document verification session. |
| `SDKKey` | String | The unique SDK key obtained from [RiskOS™](https://riskos.socure.com/accounts/developers/sdk-keys) used to authenticate the SDK. |
| `useSocureGov` | Boolean | A Boolean flag indicating whether to use the GovCloud environment. It defaults to `false`. This is only applicable for customers provisioned in the SocureGov environment. |

### Handle the response  
Your app can receive response callbacks from the `startForResult` function when the flow either completes successfully or returns with an error. The SDK represents these outcomes with the `SocureDocVSuccess` and `SocureDocVFailure` classes.

#### Success  
If the consumer successfully completes the verification flow and the captured images are uploaded to Socure's servers, the SDK returns a `SocureDocVSuccess` result. This result contains a `deviceSessionToken`, a unique identifier for the session that can be used for accessing device details about the specific session.

```kotlin
if (result is SocureDocVSuccess) {
    Log.d(TAG, "success: ${result.deviceSessionToken}")
}
```

#### Failure  
If the consumer exits the flow without completing it or an error occurs, the SDK returns a `SocureDocVFailure` result. This result contains both the `deviceSessionToken` and `SocureDocVError`, which provides specific details about the reason for failure.

```kotlin
val error = result as? SocureDocVFailure
Log.d(TAG, "error: ${error?.deviceSessionToken}, ${error?.error}")
```

When the SDK returns a failure, it provides a `SocureDocVError` enum with specific error cases relevant to the Capture App flow:

```kotlin
enum class SocureDocVError {
    SESSION_INITIATION_FAILURE,
    SESSION_EXPIRED,
    INVALID_PUBLIC_KEY,
    INVALID_DOCV_TRANSACTION_TOKEN,
    DOCUMENT_UPLOAD_FAILURE,
    CONSENT_DECLINED,
    CAMERA_PERMISSION_DECLINED,
    USER_CANCELED,
    NO_INTERNET_CONNECTION,
    UNKNOWN
}
```

The following table lists the error values that can be returned by the `SocureDocVError` enum:

| Enum Case | Error Description |
| --- | --- |
| `SESSION_INITIATION_FAILURE` | Failed to initiate the session |
| `SESSION_EXPIRED` | Session expired |
| `INVALID_PUBLIC_KEY` | Invalid or missing SDK key |
| `INVALID_DOCV_TRANSACTION_TOKEN` | Invalid transaction token |
| `DOCUMENT_UPLOAD_FAILURE` | Failed to upload the documents |
| `CONSENT_DECLINED` | Consent declined by the user |
| `CAMERA_PERMISSION_DECLINED` | Permissions to open the camera declined by the user |
| `USER_CANCELED` | Scan canceled by the user |
| `NO_INTERNET_CONNECTION` | No internet connection |
| `UNKNOWN` | Unknown error |

## Step 3: Receive the verification results  
After the consumer finishes the document capture and upload process with the Capture App, RiskOS™ runs the evaluation process and returns the results in the `evaluation_completed` webhook event. The DocV verification results are included in the `data_enrichments` array within the payload.

Alternatively, you can fetch the RiskOS™ results by making a `GET` request to the `/api/evaluation` endpoint.

JSON

```json
{
  "data": {
    "decision": "REVIEW",
    "decision_at": "2025-04-08T18:27:31.924196163Z",
    "environment_name": "",
    "eval_at": "2025-04-08T18:27:31.924196043Z",
    "eval_id": "8770e076-f568-48a9-8201-dca13087e592",
    "eval_source": "API",
    "evaluation_status": "evaluation_completed",
    "id": "abc-test-123",
    "notes": "Test Notes",
    "reason_codes": ["test"],
    "review_queues": ["Default Queue"],
    "status": "OPEN",
    "sub_status": "Surveillance",
    "tags": ["test"],
    "data_enrichments": [
      {
        "enrichment_name": "Socure Document Request",
        "enrichment_endpoint": "https://service.socure.com/api/5.0/documents/request",
        "enrichment_provider": "SocureDocRequest",
        "status_code": 200,
        "request": {
          "country": "US",
          "firstName": "John",
          "surName": "Smith"
        },
        "response": {
          "data": {
            "docvTransactionToken": "9979eda7-9694-476d-ab8b-e6bbc0153dc3",
            "eventId": "9979eda7-9694-476d-ab8b-e6bbc0153dc3",
            "qrCode": "data:image/png;base64,iVBO......K5CYII=",
            "url": "https://verify.socure.com/#/dv/9979eda7-9694-476d-ab8b-e6bbc0153dc3"
          },
          "referenceId": "b902702f-a07a-4180-acdd-20266f776ba3"
        },
        "is_source_cache": false,
        "total_attempts": 1
      },
      {
        "enrichment_name": "Socure Predictive Document Verification Prod",
        "enrichment_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
        "enrichment_provider": "Socure",
        "status_code": 200,
        "request": {
          "country": "US",
          "docvTransactionToken": "9979eda7-9694-476d-ab8b-e6bbc0153dc3",
          "firstName": "John",
          "modules": ["documentverification"],
          "parentTxnId": "e3c35948-5141-4e3d-836d-31ee7fcc8b8d",
          "surName": "Smith",
          "workflow": "api_consumer_onboarding"
        },
        "response": {
          "documentVerification": {
            "decision": {
              "name": "standard",
              "value": "accept"
            },
            "documentType": {
              "country": "USA",
              "state": "WA",
              "type": "Drivers License"
            },
            "reasonCodes": [
              "I834",
              "I845",
              "I831",
              "I820",
              "I836",
              "I838",
              "R823",
              "R822"
            ]
          },
          "referenceId": "06bf2f66-7d18-47c2-b12f-4be3a30e1d49"
        },
        "is_source_cache": false,
        "total_attempts": 1
      },
      {
        "enrichment_name": "Socure Image Request Prod",
        "enrichment_endpoint": "https://upload.socure.com/api/5.0/documents/{referenceId}",
        "enrichment_provider": "SocureImageRequest",
        "status_code": 200,
        "request": {
          "referenceId": "06bf2f66-7d18-47c2-b12f-4be3a30e1d49"
        },
        "response": {
          "docId": "077bd0be-129e-4352-bb6b-cc07c9a86fdc"
        },
        "is_source_cache": false,
        "total_attempts": 1
      }
    ],
    "workflow": "api_consumer_onboarding",
    "workflow_id": "7ba6948f-502d-446e-a1e5-45d66cc50983",
    "workflow_version": "1.0.0"
  },
  "event_at": "2025-04-08T18:27:31.9244894Z",
  "event_id": "df9252b5-85c8-426e-9590-8f51b6e5b5c0",
  "event_type": "evaluation_completed"
}
```