User Guides
Home
Start typing to search…

Android SDK

Learn how to quickly integrate with the Predictive Document Verification (DocV) Android SDK v5.

📘

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:

Get a valid API key from the Developer Workbench > API Keys page in RiskOS™.
Get a valid SDK key from the Developer Workbench > SDK Keys page in RiskOS™.
(Optional) Add your IP address to the allowlist in RiskOS™.

Android SDK integration notes

The DocV SDK is compiled with the following:

  • compileSdkVersion: 34
  • Java: 17

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.


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:
ParameterRequiredDescription
languageOptional

Determines the language package for the UI text on the Capture App.

Note: Socure can quickly add support for any new language requirement that is not listed above. For more information, contact [email protected].

use_case_keyOptional

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

  • If this field is empty, the Capture App will use the flow marked as Default in RiskOS™.
  • If the value provided is incorrect, the SDK will return an Invalid Request error.
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",
    "eval_id": "6dc8f39c-ecc3-4fe0-9283-fc8e5f99e816",
    "workflow": "consumer_onboarding",
    "data": {
      "individual": {
        "id": "9876543",
        "first_name": "John",
        "middle_name": "M",
        "last_name": "Doe",
        "national_id": "000-10-0007",
        "dob": "2002-07-28",
        "email": "[email protected]",
        "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.


  1. When you receive the API response, collect the docvTransactionToken. This value is required to initialize the DocV Android SDK.
{
  "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:

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

dependencies {
    implementation 'com.socure.android:docv-capture:5.0.0'
}

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:

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

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:

ParameterTypeDescription
docVTransactionTokenStringThe transaction token retrieved from the API response of the /api/evaluation endpoint. Required to initiate the document verification session.
SDKKeyString

The unique SDK key obtained from RiskOS™ used to authenticate the SDK.

useSocureGovBoolean

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.

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.

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:

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 CaseError Description
SESSION_INITIATION_FAILUREFailed to initiate the session
SESSION_EXPIREDSession expired
INVALID_PUBLIC_KEYInvalid or missing SDK key
INVALID_DOCV_TRANSACTION_TOKENInvalid transaction token
DOCUMENT_UPLOAD_FAILUREFailed to upload the documents
CONSENT_DECLINEDConsent declined by the user
CAMERA_PERMISSION_DECLINEDPermissions to open the camera declined by the user
USER_CANCELEDScan canceled by the user
NO_INTERNET_CONNECTIONNo internet connection
UNKNOWNUnknown error

Step 3: Receive the verification results

After the consumer finishes the document capture and upload process with the Caprture 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.

{
  "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": [
      {
        "third_party_name": "Socure Document Request",
        "third_party_endpoint": "https://service.socure.com/api/5.0/documents/request",
        "third_party_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
      },
      {
        "third_party_name": "Socure Predictive Document Verification Prod",
        "third_party_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
        "third_party_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
      },
      {
        "third_party_name": "Socure Image Request Prod",
        "third_party_endpoint": "https://upload.socure.com/api/5.0/documents/{referenceId}",
        "third_party_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"
}

Updated 4 days ago