Example Integrations

Your Predictive Document Verification (DocV) SDK integration provides access to a range of identity verification services within RiskOS™ that enable you to integrate with the following DocV services:

Document Verification allows you to confirm the authenticity of a government-issued ID, match the Personal Identifiable Information (PII) extracted from the ID against the input information, and match the ID headshot to a consumer-submitted selfie using facial biometric analysis.

This scenario can also be implemented in a Top of the Funnel use case to verify the consumer's identity at the beginning of your onboarding process, or in a Step Up Authentication use case, where multiple authentication sources are required to mitigate fraud risk.

How it works

The following example workflow outlines how to integrate RiskOS™ with the DocV SDKS:

On the DocV App page in RiskOS™, create a new Capture App flow using a flow template. After you have configured and customized your flow, publish it to the Production environment.
When a consumer wants to verify their identity, trigger RiskOS™ in your application by making a POST request to the /api/evaluation endpoint to generate a DocV transaction token (docvTransactionToken) and initiate the RiskOS™ workflow.

📘
Tip:
In the body of the API request, be sure to pass the name of the custom Capture App flow you created in RiskOS™ in the data.individual.docv.config.use_case_key field.

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 a182150a-363a-4f4a-xxxx-xxxxxxxxxxxx' \
  --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"
        }
      }
    }
  }'

{
    "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"
}

Next, pass your SDK key and the docvTransactionToken value in the launch function to initialize the DocV SDK.

func onButtonTapped() {
    let options = SocureDocVOptions(
        publicKey: "SOCURE_SDK_KEY",
        docVTransactionToken: "78d1c86d-03a3-4e11-b837-71a31cb44142",
        presentingViewController: self,
        useSocureGov: false
    )

    SocureDocVSDK.launch(options) { (result: Result<SocureDocVSuccess, SocureDocVFailure>) in
        switch result {
        case .success(let success):
            print("Flow succeeded: \(success)")
        case .failure(let failure):
            print("Flow failed due to \(failure)")
        }
    }
}

class Activity : AppCompatActivity() {

    private lateinit var startForResult: ActivityResultLauncher<Intent>

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ... your setup code

        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,
                    SOCURE_SDK_KEY,
                    useSocureGov
                )
            )
        )
    }
}

function start() {
  SocureDocVSDK.launch(
    "SOCURE_SDK_KEY",
    "docvTransactionToken",
    "#websdk",
    config
  );
}

launchSocureDocV(
  "docVTransactionToken",
  "SOCURE_SDK_KEY",
  userSocureGov,
  onSuccess,
  onError
);

The consumer is redirected to the Capture App, which guides them through the document and selfie image capture process then uploads the images to Socure's servers. When the process is complete, your SDK integration can receive a success callback.
RiskOS™ then completes 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"
}