Understanding IDV & Biometrics

Locating IDV & Biometrics Results

Once a workflow has been executed, the detailed results are nested within the overall workflowResult object. To find the specific outcomes of IDV and Biometric checks, you must navigate the JSON structure.

1. Start with workflowStepResults: In the workflowResult, find the workflowStepResults array.
2. Identify IDV Steps: Look for steps with names (stepName) like IDV_DOCUMENT_CHECK, IDV_FACIAL_COMPARISON, IDV_FACIAL_LIVENESS, and IDV_OCR_COMPARISON.
3. Examine processResults: Inside each relevant step result is a processResults array. Each object here is a Process Result Object (PRO) containing granular data.
4. Drill into supplementaryData: The richest details are in the supplementaryData object within a PRO. The type field here is crucial as it defines the structure and meaning of the data.

Decoding supplementaryData for IDV Checks

The structure of the supplementaryData object is determined by its type. For IDV and Biometrics, you will encounter several key types.

Type: IDV_DOCUMENT

This object contains the results of the automated analysis of a submitted identity document, assessing its authenticity and integrity.

1
"supplementaryData": {
2
  "type": "IDV_DOCUMENT",
3
  "outcomeRaw": "clear",
4
  "resultMap": {
5
    "visual_authenticity": { "resultNormalized": "clear" },
6
    "image_integrity": { "resultNormalized": "clear" },
7
    "data_validation": { "resultNormalized": "clear" },
8
    "compromised_document": { "resultNormalized": "clear" }
9
  },
10
  "detectedDocumentType": "DRIVERS_LICENSE",
11
  "detectedDocumentCountry": "AUS"
12
}

Key Fields:

• outcomeRaw: The original, unprocessed result from the IDV service provider.
• resultMap: A map containing the results of specific checks. Keys like visual_authenticity, image_integrity, and data_validation indicate the status of different verification aspects.
• detectedDocumentType: The type of document the system identified (e.g., DRIVERS_LICENSE, PASSPORT).
• detectedDocumentCountry: The ISO 3166-1 alpha-3 country code of the document as detected by the provider.

Type: IDV_FACIAL_COMPARISON

This object provides the results of comparing a user’s selfie with the photo on their identity document to confirm they are the same person.

1
"supplementaryData": {
2
  "type": "IDV_FACIAL_COMPARISON",
3
  "outcomeRaw": "clear",
4
  "resultMap": {
5
    "face_comparison": {
6
        "confidence": 99.99,
7
        "resultNormalized": "clear"
8
    }
9
  },
10
  "comparedDocumentId": "92de15f6-5717-4562-b3fc-2c963f6665a7",
11
  "comparedSelfieId": "58e0a7e3-0c3f-4e20-95af-0a4a8332d383"
12
}

Key Fields:

• resultMap: Contains metrics from the comparison. The face_comparison key often includes a confidence score.
• comparedDocumentId: The unique ID of the identity document used.
• comparedSelfieId: The unique ID of the selfie document used.

Type: IDV_FACIAL_LIVENESS

This object contains the results of the liveness check, which verifies that the selfie was captured from a live person and not a spoof attempt (e.g., a photo of a photo).

1
"supplementaryData": {
2
  "type": "IDV_FACIAL_LIVENESS",
3
  "outcomeRaw": "clear",
4
  "resultMap": {
5
    "liveness_detection": {
6
        "confidence": 98.7,
7
        "resultNormalized": "clear"
8
    }
9
  },
10
  "comparedSelfieId": "58e0a7e3-0c3f-4e20-95af-0a4a8332d383"
11
}

Key Fields:

• resultMap: Contains the outcome of the liveness test. The liveness_detection key will often have a confidence score.
• comparedSelfieId: The unique ID of the selfie document that was analyzed.

Types: IDV_OCR & IDV_OCR_COMPARISON

The Optical Character Recognition (OCR) process is crucial for extracting data and verifying it against user-provided information. This typically generates two distinct PROs.

1. IDV_OCR: This object holds the raw data extracted directly from the identity document image. The resultMap will contain key-value pairs of the fields read from the document, such as full_name, document_number, and date_of_birth.

2. IDV_OCR_COMPARISON: This object compares the data extracted via OCR with the data already present on the entity. It is used to flag discrepancies.

1
"supplementaryData": {
2
  "type": "IDV_OCR_COMPARISON",
3
  "outcomeRaw": "suspected",
4
  "resultMap": {
5
    "last_name_match": { "resultNormalized": "clear" },
6
    "date_of_birth_match": { "resultNormalized": "clear" }
7
  },
8
  "mismatchMap": {
9
    "first_name_match": {
10
      "originalData": "Jon",
11
      "reviewedData": "John",
12
      "resultNormalized": "suspected"
13
    }
14
  },
15
  "comparisonSource": "ENTITY"
16
}

Key IDV_OCR_COMPARISON Fields:

• resultMap: Indicates which fields matched successfully.
• mismatchMap: Crucially, this highlights any fields that did not align, showing the original vs. the OCR-extracted data.
• comparisonSource: Specifies what the OCR data was compared against, either ENTITY data or OCR_UPDATE data.

IDV Issues and Risk Factors

The results from the supplementaryData objects are used to generate specific issues and risk factors that help in decision-making.

• Issues: When a check result is SUSPECTED or REJECTED, a corresponding issue is typically created. For example, a REJECTED IDV_FACIAL_LIVENESS result will generate a LIVENESS_DETECTION issue with a WARNING severity.
• Risk Factors: The status of each check (CLEAR, SUSPECTED, REJECTED) is also converted into a risk factor (e.g., idv_document_result, idv_facial_comparison_result) which contributes to the entity’s overall risk score.

Overriding and Invalidating Results

• Overriding: If you disagree with an automated result (e.g., a SUSPECTED OCR mismatch), you can manually override it. By calling PATCH /v2/individuals/{entityId}/results/idv and providing the processResultId of the relevant PRO, you can change its manualStatus to CLEAR.
• Invalidation: IDV results can be automatically invalidated. For example, if an entity’s name or date of birth is updated after a successful OCR check, the original OCR PRO’s systemStatus will be changed from VALID to STALE or MARKED_INVALID to indicate that the result is no longer based on the most current entity data.