KYCKey FeaturesIDV & Biometrics

Understanding IDV and Biometrics

Learn how to read IDV and Biometrics results.

Understanding IDV & Biometric Check Results

When initiating an IDV process through the OneSDK, it is typically executed as part of a broader workflow. These workflows in FrankieOne consist of a series of automated checks and processes designed to deliver a thorough evaluation. An IDV check serves as one component within this workflow, which may also encompass AML checks, risk assessments, and other compliance-related procedures, ensuring a holistic approach to identity verification and risk management.

1"requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
2"workflowResult": {
3    "schemaVersion": 0,
4    "workflowName": "string", // For example, "IDV Check"
5    "workflowExecutionId": "string",
6    "workflowExecutionState": "COMPLETED",
7    "status": "UNCHECKED",
8    "statusOverrideAt": "2025-05-05T11:43:23.488Z",
9    "statusOverrideRequestId": "02HN9XHZN6MGXM9JXG50K59Q85",
10    "statusOverrideBy": "operator-123",
11    "riskAssessment": {..}, // Risk assessment details
12    "isManual": true,
13    "steps": {..}, // Workflow Steps that passed, failed, or incomplete
14    "startedAt": "2025-05-05T11:43:23.488Z",
15    "endedAt": "2025-05-05T11:43:23.488Z",
16    "issues": {..}, // Issues related to the workflow
17    "lifecyclePhase": "KYC", // The lifecycle phase of the customer in which this workflow would be executed
18    "monitoringTypes": {..},
19    "workflowId": "string",
20    "requestId": "string",
21    "entityId": "string",
22    "entityType": "INDIVIDUAL",
23    "serviceProfileId": "string",
24    "endWorkflowId": "string",
25    "endWorkflowName": "string",
26    "workflowStepResults": {..},
27    "result": "UNCHECKED", // Outcome of this workflow execution.
28    "errors": {..},
29    "notes": {..},
30    "createdAt": "2025-05-05T11:43:23.488Z",
31    "updatedAt": "2025-05-05T11:43:23.488Z",
32    "updatedBy": "string",
33}

Workflow Step Results

Each step in a workflow generates a Workflow Step Result, which encapsulates the outcomes and insights from that specific step. Within each Workflow Step Result, you’ll find one or more Process Result Objects (PROs). These PROs provide granular details about the checks performed, including their type, results, and supplementary data.

The workflowStepResults array organizes the results of a workflow, with each element representing the outcome of a particular step. Each Workflow-Execution-Step-Result includes critical information such as the step’s name, overall result, detailed summaries, and any associated process results. This structure allows for a comprehensive understanding of the workflow’s execution and its individual components.

Key Components

  1. Step Name (stepName)
    Identifies the specific step in the workflow (e.g., IDV_DOCUMENT_CHECK, IDV_FACIAL_COMPARISON). This helps you understand which part of the IDV process the result pertains to.

  2. Result (result)
    Indicates the overall outcome of the step. Possible values include:

    ValueDescription
    UNCHECKEDStep was not attempted.
    SKIPPEDStep was skipped as it wasn’t required.
    MISSING_DATAStep requires additional data.
    PASSStep completed successfully.
    FAILStep completed but did not meet the required criteria.
    COMPLETEStep finished successfully (no pass/fail).
    INCOMPLETEStep was unable to finish successfully.
    MATCHStep produced a successful match.
    NO_MATCHStep produced no match.
    PARTIALStep produced a partially successful match.
    CLEARNo negative matches were found.
    HITA negative match was found.
    CLEAREDPreviously found matches have been resolved.
    EXPIREDData found has expired.
    NOT_APPLICABLEStep was not necessary.
    ERRORAn unrecoverable error occurred.

  3. Summary (summary)
    Provides a detailed, step-specific summary of the results. For IDV-related steps, this might include summaries like Workflow-Step-Summary-ID, which offer insights into document matching, facial comparison, or other IDV checks.

  4. Process Results (processResults)
    For the most granular details, examine the processResults array within each Workflow-Execution-Step-Result. Each object in this array is a PRO related to a specific aspect of the IDV process. To understand the specifics of an IDV check, review the supplementaryData field within these PROs.

Interpreting Step Results

By examining the result of each IDV-related step, you can quickly understand the high-level outcome of that specific check. For example:

  • A step named IDV_DOCUMENT_CHECK with a result of PASS indicates that document verification was successful.
  • A step named IDV_FACIAL_COMPARISON with a result of FAIL suggests that the facial comparison did not meet the required criteria.
1"workflowStepResults" {
2    "stepResultId": "string",
3    "workflowExecutionId": "string",
4    "stepName": "string", // The name of the step
5    "requestId": "string",
6    "objectType": "DOCUMENT", // The type of primary object that was checked (e.g. NAME or DOCUMENT)
7    "objectId": "string",
8    "serviceProviders": {..},
9    "result": "CHECKED", // Overall result of the step Depending on the context of the step and what it's trying to do.
10    "errors": {..}, // Workflow step errors
11    "summary": {..}, // Check here for the summary of the ID step
12    "risk": {..},
13    "notes": {..},
14    "processResults": {..}, // Array of process result objects
15    "createdAt": "2025-05-05T11:43:23.488Z",
16    "updatedAt": "2025-05-05T11:43:23.488Z",
17    "updatedBy": "string",
18}

Workflow-Step-Summary-ID

The summary field offers a concise overview of the results for a specific workflow step. It typically includes details such as the total number of checks performed, the number of successful matches, and any associated metadata.

For workflow steps where the objectType is DOCUMENT or pertains to IDV, the summary field may contain a Workflow-Step-Summary-ID object. This object provides a detailed summary of the ID matching process, including:

  • The number of matches found for each document checked.
  • The type of match (e.g., “gov_id” for government-issued IDs or “other_id” for alternative documents).
  • Verification status and whether all required sources were successfully matched.

This summary helps streamline the interpretation of IDV results by presenting key insights in a structured and easily digestible format.

1{
2  "stepData": {
3    "documentId_1": {
4      "matchType": "gov_id",
5      "matchCount": 2,
6      "isVerified": true
7    },
8    "documentId_2": {
9      "matchType": "other_id",
10      "matchCount": 1,
11      "isVerified": false
12    }
13    // ... more document IDs and their match details
14  },
15  "matchCount": 3, // Total number of matches across all checked documents
16  "matchCountRequired": 1, // The number of distinct matches required for this step
17  "hasAllRequiredSourcesMatched": true, // Indicates if all necessary data sources were checked and matched
18  "isVerified": true, // Overall verification status based on the matching requirements
19  "stepName": "ID_MATCHING"
20}

Workflow Step Risk

The risk field offers a detailed risk assessment for the workflow step. It includes the overall risk level, the score contributed by this step to the total risk, and a breakdown of specific risk factors evaluated during the process. This information helps identify potential vulnerabilities and supports informed decision-making.

1"risk": {
2    "level": "string",
3    "contributedScore": 0,
4    "overallScore": 0,
5    "factors": [
6    {
7        "factor": "string", 
8        "score": 0,
9        "value": "string"
10    }
11    ]
12}

Workflow Step Service Providers

The serviceProviders field provides details about the service providers utilized during the IDV check. Each object in this array represents a specific provider and includes key information such as the provider’s name, the outcome of their analysis, and the sequence in which their services were executed. This field helps trace the contributions of individual providers to the overall verification process.

1"serviceProviders": [
2    {
3    "provider": "DVS",
4    "result": "CLEAR",
5    "order": 0,
6    }
7],

Process Result Objects (PROs)

The process results are a critical component of the IDV check outcomes, offering granular insights into the checks performed and their results. These results are encapsulated within the processResults array of a workflow step result, with each object representing a Process Result Object (PRO) tied to a specific aspect of the IDV process.

Each PRO in the processResults array includes:

  • Check Type: Specifies the type of check performed (e.g., document verification, facial comparison, liveness detection).
  • Outcome: Indicates the result of the check (e.g., pass, fail, incomplete).
  • Supplementary Data: Provides detailed metrics, scores, and additional context relevant to the check.

By thoroughly analyzing the workflowStepResults and their associated PROs, you can gain a comprehensive understanding of the IDV process, including its successes, failures, and areas requiring further attention.

For detailed insights into an IDV check, focus on the supplementaryData field within each PRO. This field contains key information such as extracted document data, facial similarity scores, and liveness detection results.

1"processResults": {
2    "processResultId": "string",
3    "schemaVersion": 0,
4    "entityId": "string",
5    "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
6    "stepName": "string",
7    "stepType": "string",
8    "objectType": "string",
9    "objectId": "string",
10    "createdAt": "2025-05-05T11:43:23.488Z",
11    "updatedAt": "2025-05-05T11:43:23.488Z",
12    "groupId": "string",
13    "providerResult": {..},
14    "result": "MATCH",
15    "class": "KYC",
16    "supplementaryData": {..},
17    "errors": {..},
18    "notes": {..},
19    "systemStatus": "VALID",
20    "manualStatus": "TRUE_POSITIVE",
21    "state": "IN_PROGRESS",
22    "riskFactors": {..},
23    "updatedBy": "string",
24}

PRO Provider Result

The providerResult field encapsulates the analysis performed by the IDV provider. It includes details such as the provider’s name, the source of the data, confidence levels, risk scores, and any errors encountered during the verification process. This field provides critical insights into the provider’s evaluation and helps diagnose potential issues.

1"providerResult": {
2    "name": "string",
3    "source": "string",
4    "sourceNormalized": "string",
5    "reference": "string",
6    "fuzziness": {
7        "normalized": 100,
8        "actual": "string"
9    },
10    "confidence": {
11        "normalized": 100,
12        "actual": "string"
13    },
14    "riskScore": 0,
15    "errorCode": "string",
16    "errorMessage": "string"
17}

PRO Errors

The errors field provides detailed information about any issues encountered during the IDV process. These errors may arise from document verification, biometric matching, or other verification steps. Each error object typically includes the following:

  • Code: A unique identifier for the error.
  • Description: A brief explanation of the issue.
  • Location: The specific part of the process where the error occurred.

This information is essential for diagnosing and resolving problems in the IDV workflow.

1"errors": [
2    {
3        "code": "string",
4        "description": "string",
5        "location": "string"
6    },
7    {
8        "code": "string",
9        "description": "string",
10        "location": "string"
11    }
12],

PRO Notes

The notes field captures supplementary information or annotations associated with the IDV check. This may include operator comments, system-generated insights, or any contextual details that provide clarity or additional understanding of the verification process.

1"notes": {
2    "additionalProp1": {
3    "type": "string",
4    "value": "string"
5    },
6    "additionalProp2": {
7    "type": "string",
8    "value": "string"
9    },
10    "additionalProp3": {
11    "type": "string",
12    "value": "string"
13    }
14},

PRO Risk Factors

The riskFactors field offers a detailed breakdown of the risk elements evaluated during the IDV process. Each risk factor includes a descriptive label and a corresponding value that quantifies its impact or significance. This data provides valuable insights into potential vulnerabilities or concerns, enabling you to assess the overall risk profile and make well-informed decisions based on the verification outcomes.

1"riskFactors": {
2    "factor": "string",
3    "value": "string"
4}

PRO Supplementary Data

The supplementaryData field is a critical component of the process result object, offering detailed insights into the IDV checks performed. Its structure varies depending on the type of check and the provider used. Key elements of the supplementaryData field include:

  • Check Results: Outcomes of the IDV checks, such as document verification, facial comparison, or liveness detection, often accompanied by relevant scores or metrics.
  • Check Status: Indicates whether the checks passed, failed, or remain incomplete.
  • Metadata: Additional details about the checks, such as timestamps, error messages, or provider-specific information.
  • Associated IDs: References to the IDs of documents, selfies, or other artifacts involved in the checks.
  • Analyzed Types: Specifies the types of documents or biometric data analyzed during the process.

For IDV-related Process Result Objects (PROs), the supplementaryData field typically adheres to one of several predefined structures, tailored to the specific type of check being performed. These structures provide a comprehensive view of the verification process, enabling detailed analysis and troubleshooting.

Supplementary Data for IDV Checks

Below is an overview of the various types of supplementaryData objects you may encounter during IDV checks, along with guidance on interpreting their key fields and understanding their significance:

IDV-Document

This structure offers detailed insights into the analysis of the submitted identity document, evaluating its authenticity and determining the likelihood of it being a valid ID document.

1{
2  "type": "string", // e.g., "DOCUMENT"
3  "outcomeRaw": "string", // The raw outcome reported by the IDV provider
4  "resultMap": { // Key-value pairs providing detailed results
5    // Refer to enum: SupplementaryDataIDVEnumDataDocument for possible keys
6    // Examples:
7    // "document_validity": "PASS",
8    // "document_type_match": "TRUE"
9  },
10  "detectedDocumentType": "string", // The type of document detected (e.g., "DRIVERS_LICENSE", "PASSPORT")
11  "detectedDocumentCountry": "string" // The ISO-3166-alpha3 country code of the detected document
12}

Key Interpretation Points:

  • outcomeRaw: This provides the original, unprocessed result from the IDV service. It can be useful for debugging or understanding the provider’s direct assessment.
  • resultMap: This is a crucial field containing specific findings about the document. Consult the SupplementaryDataIDVEnumDataDocument enum in the API specifications for a comprehensive list of possible keys and their meanings. Common keys might indicate the validity of the document, whether the document type matches expectations, checks for tampering, etc.
  • detectedDocumentType and detectedDocumentCountry: These fields confirm the type and origin of the analyzed document.

IDV-Facial-Comparison

This structure provides the results of comparing the user’s selfie with the photo on their submitted identity document. It evaluates the likelihood and accuracy of the facial match between the two, ensuring the person presenting the ID is the same as the individual in the document.

1{
2  "type": "string", // e.g., "FACIAL_COMPARISON"
3  "outcomeRaw": "string", // The raw outcome reported by the IDV provider
4  "resultMap": { // Key-value pairs providing detailed results
5    // Refer to enum: SupplementaryDataIDVEnumDataFacialComparison for possible keys
6    // Examples:
7    // "similarity_score": "0.95",
8    // "face_match": "TRUE"
9  },
10  "comparedDocumentId": "string (uuid)", // The ID of the compared ID document
11  "comparedSelfieId": "string (uuid)" // The ID of the compared selfie
12}

Key Interpretation Points:

  • outcomeRaw: The direct result of the facial comparison from the provider.
  • resultMap: Contains specific metrics and outcomes of the comparison. Common keys might include a similarity score and a boolean indicating if a match was found based on a defined threshold. Refer to SupplementaryDataIDVEnumDataFacialComparison for all possible keys.
  • comparedDocumentId and comparedSelfieId: These link back to the specific document and selfie involved in the comparison, allowing you to trace which artifacts were analyzed.

IDV-Facial-Liveness

This structure represents the results of a facial liveness check, determining whether the submitted facial image or video is genuine and captured from a live individual, rather than being a spoof attempt.

1{
2  "type": "string", // e.g., "FACIAL_LIVENESS"
3  "outcomeRaw": "string", // The raw outcome reported by the IDV provider
4  "resultMap": { // Key-value pairs providing detailed results
5    // Refer to enum: SupplementaryDataIDVEnumDataFacialLiveness for possible keys
6    // Examples:
7    // "liveness_detected": "TRUE",
8    // "spoofing_score": "0.02"
9  },
10  "comparedSelfieId": "string (uuid)" // The ID of the selfie analyzed for liveness
11}

Key Interpretation Points:

  • outcomeRaw: The provider’s direct assessment of liveness.
  • resultMap: Contains specific details about the liveness check. Keys might indicate if liveness was detected and potentially a score representing the likelihood of a live person. Consult SupplementaryDataIDVEnumDataFacialLiveness for all possible keys.
  • comparedSelfieId: Identifies the specific selfie that was analyzed for liveness.

IDV-OCR

This structure represents the results of Optical Character Recognition (OCR) performed on the submitted identity document. It ensures accuracy and consistency by comparing the extracted document data with updated or alternate data provided during the verification process.

1{
2  "type": "string", // e.g., "OCR"
3  "outcomeRaw": "string", // The raw outcome reported by the IDV provider
4  "resultMap": { // Key-value pairs containing the extracted data
5    // Refer to enum: SupplementaryDataIDVEnumDataOCR for possible keys
6    // Examples:
7    // "full_name": "John Doe",
8    // "document_number": "ABC12345",
9    // "expiry_date": "2026-12-31"
10  },
11  "scannedDocumentId": "string (uuid)", // The ID of the document that was scanned
12  "scannedAttachmentFrontId": "string (uuid)", // The ID of the front image attachment
13  "scannedAttachmentBackId": "string (uuid)" // The ID of the back image attachment (if applicable)
14}

Key Interpretation Points:

  • outcomeRaw: The provider’s overall result of the OCR process.
  • resultMap: This is where the extracted data from the document is stored as key-value pairs. The keys will correspond to the fields recognized on the document (e.g., name, document number, date of birth). Refer to SupplementaryDataIDVDataOCR enum for possible keys.
  • scannedDocumentId, scannedAttachmentFrontId, scannedAttachmentBackId: These IDs link back to the specific document and image attachments that were processed by OCR.

IDV-OCR-Comparison

This structure provides a comprehensive comparison between data extracted via OCR and other sources, such as user-provided information or pre-existing entity records.

It highlights matches and discrepancies between the scanned document data and the entity’s stored or updated details, ensuring data accuracy and consistency. Priority is given to the entity’s stored details (used for verification with service providers) over the updated data extracted from the OCR scan.

1{
2  "type": "string", // e.g., "OCR_COMPARISON"
3  "outcomeRaw": "string", // The raw outcome reported by the IDV provider
4  "resultMap": { // Key-value pairs indicating comparison results
5    // Refer to enum: SupplementaryDataIDVEnumDataOCRComparison for possible keys
6    // Examples:
7    // "name_match": "TRUE",
8    // "dob_match": "FALSE"
9  },
10  "ocrResultId": "string (uuid)", // The PRO ID of the OCR data used for comparison
11  "comparisonSource": "string", // e.g., "ENTITY", "UPDATED_DATA"
12  "mismatchMap": { // Key-value pairs highlighting specific mismatches
13    // Refer to enum:

Additional Resources