> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
```json theme={null}
"supplementaryData": {
"type": "IDV_DOCUMENT",
"outcomeRaw": "clear",
"resultMap": {
"visual_authenticity": { "resultNormalized": "clear" },
"image_integrity": { "resultNormalized": "clear" },
"data_validation": { "resultNormalized": "clear" },
"compromised_document": { "resultNormalized": "clear" }
},
"detectedDocumentType": "DRIVERS_LICENSE",
"detectedDocumentCountry": "AUS"
}
```
**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.
```json theme={null}
"supplementaryData": {
"type": "IDV_FACIAL_COMPARISON",
"outcomeRaw": "clear",
"resultMap": {
"face_comparison": {
"confidence": 99.99,
"resultNormalized": "clear"
}
},
"comparedDocumentId": "92de15f6-5717-4562-b3fc-2c963f6665a7",
"comparedSelfieId": "58e0a7e3-0c3f-4e20-95af-0a4a8332d383"
}
```
**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).
```json theme={null}
"supplementaryData": {
"type": "IDV_FACIAL_LIVENESS",
"outcomeRaw": "clear",
"resultMap": {
"liveness_detection": {
"confidence": 98.7,
"resultNormalized": "clear"
}
},
"comparedSelfieId": "58e0a7e3-0c3f-4e20-95af-0a4a8332d383"
}
```
**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.
```json theme={null}
"supplementaryData": {
"type": "IDV_OCR_COMPARISON",
"outcomeRaw": "suspected",
"resultMap": {
"last_name_match": { "resultNormalized": "clear" },
"date_of_birth_match": { "resultNormalized": "clear" }
},
"mismatchMap": {
"first_name_match": {
"originalData": "Jon",
"reviewedData": "John",
"resultNormalized": "suspected"
}
},
"comparisonSource": "ENTITY"
}
```
**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.
FrankieOne employs fuzzy matching logic (Levenshtein distance) for OCR comparison to account for minor typos or OCR errors. For example, a Levenshtein distance of 1 or 2 might be allowed for names before a mismatch is flagged as `SUSPECTED`.
## 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.