Process the Proof Results

The application must wait for the user to complete the Proof, then obtain and analyze the results.

Proof Status

When the user completes Proof, the status changes from 0 - Pending to 1 - Accepted, and the results are ready to be picked up immediately. Refer, to the Transaction Status section for more details.

📘

Common Transaction Status

The Transaction Status is common between Proof (Identity Verification) and Verified (Authentication) workflows.

The application has several ways to detect when the status changes.

  • Periodic poll of backend for Proof operation status change using Operation Status Endpoint
  • Embedded Integration can listen to Web Component Events for web integration or to JavaScript bridge events for WebView integration. The UI emits the signal that the user has reached the "final page" of the experience.

Please refer to the Web Component Events section for more details.

The best strategy from both a UX transition reaction time and system load perspective is to:

  • Listen to events from the Web Component / WebView.
  • When the user reaches the final page, pass the signal from your application frontend to your application's backend.
  • Confirm the status change via the backend Operation Status Endpoint.
  • As a backup, poll status changes periodically using Operation Status Endpoint, for example, once every 5 seconds.

Both Out-of-band and Embedded integrations can use Webhook to receive notifications when the status changes. Note that webhooks are not queued and do not have guaranteed delivery, so the periodic polling backup strategy still applies.

Get Proof Results

When Proof status is 1 - Accepted the results are ready to be retrieved using Operation Result Endpoint

The application needs to ingest and inspect the results, the beginning part of Proof Results v2 sample JSON is shown below:

{
    "Name": "GetForeignIDDocument",
    "OperationId": "e09febaa-3b64-b632-1236-4f491d48b47c",
    "Payload": {
        "Data": {
            "VerificationSteps": {
                ...
            },
            "Document": {
                "Description": "Document Image",
                "Type": "2",
                "CapMethod": 2,
                "RawData": [
                    ...
                ],
                "Data": [
                    {
                        "Key": "Page1Name",
                        "Value": "United States - Georgia Driving License (2019) Real"
                    },
                    {
                        "Key": "Page1Probability",
                        "Value": "0.96807367"
                    },
                    {
                        "Key": "Page2Name",
                        "Value": "United States - Georgia Driving License (2019) Side B"
                    },
                    {
                        "Key": "Page2Probability",
                        "Value": "0.9040118"
                    },
                      
                    ...

Results JSON Values Description

The Proof result object schema can be inspected at Proof Result - GetIDDocument API Swagger UI endpoint description.

For V1 legacy API, the information is located in the Data object. If developers follow the guide for the current V2 version of the API, the information is located in the Payload.Data object.

Payload.Data contents reference:

Key NameContent and DescriptionData Format​
DocumentThe object contains data elements extracted from the document.JSON Object
Document.DataThe array of key-value pairs of fields obtained from the document via OCR / MRZ / Barcodes(s) decode. The possible values for keys are listed in the  fieldTypes csv document provided on demandArray of Key/Value Pairs
Document.Data.BarcodeSecurityThis field denotes whether the document (including US, Mexican, and Canadian IDs) has successfully passed barcode security validation.PASS or FAIL
Document.Data.padResultThis field indicates whether the presented document has successfully passed liveness detection. Additional details can be found in the Document.RawData in Ipsidy.Bus.Pad.Score keyPASS or FAIL
Document.Data.mismatchMrzOcrThis field denotes if there is been a significant mismatch between the OCR and MRZ/PDF417 datatrue or null
Document.RawDataThe array contains various objects depending on features enabled in configuration on a per-customer basis.escaped JSON
Document.AdditionalImagesAn array containing objects with images cropped from document capture. The “Description” gives details of the contents of an array element. The contents depend on the document type. Some examples of Description values:

- Document front side  
- Document back side
- Ghost portrait
An array of objects containing base64-encoded images
Document.FacialImageContains cropped document owner’s photo (aka mugshot) personalization element, usually found on the “front” side of the document. DataType key is the enum describing image format, refer to the schema.The object containing base64-encoded image.
CurrentFacialImageThe object contains a live user selfie. DataType key is the enum describing image format, please see schema. Base64-encoded image
Document.RawData.FacialImageInformationThis field supplies the coordinates of the user's face within the selfie, enabling the Selfie image to be cropped for privacy. Coordinates of the user's face within the selfie image
MatchedContains the result of comparing a person’s selfie to a document. Additional information is provided in MatchProbabiltytrue or false
MatchProbabiltyContains inverse (1-x) of False Match Probability value from 0 to 1
MatchScoreLogarithm-based (base 10) score output of the matching algorithminteger
BiometryProcessingResultShould be disregarded as it contains technical information. Do NOT use the liveness metrics contained in this object.
LivenessDetectionResultContains object describing the genuine presence detection/presentation attack detection details, the AI model version, quality metric, etc..  IsLive element contains system decision.
LivenessDetectionResult.IsLiveThe field indicates if the user's selfie has successfully passed the liveness detection.true or false​
GeofencingContains select elements describing the end user environment.

The top-level JSON object also contains additional elements:

  • Metadata contains elements that are kept in the audit trail after PII is removed
  • Tag contains the tag element that can be provided via API during transaction initialization, and can be used for tracing /reporting purposes.

🚧

Warning

The key case for padResultand mismatchMrzOcrmay change from the camelCase to PascalCase in subsequent releases.

Save Proof Results

authID only retains user-provided documents and other PII data for 7 days.

Developers can choose to parse and save individual objects/keys into the permanent storage of the user application (user database).

Developers can also get a pre-formatted PDF of Proof details with all PII data, as displayed in the Identity Portal, using the dedicated authID Reports API. Use the Ledger formatting option when generating Proof report PDF as the default choice may have margin/formatting issues.

Inspect Proof Results

The logic deciding if a user can proceed with onboarding must be taken into account in the following checklist.

Inspection StepProof Result KeyDescription
Check if document biometry matches the user's selfie.MatchedContains true or false and shows if the document image matches user biometry (selfie).
Check if the user has passed the genuine presence detection/liveness test.LivenessDetectionResult.IsLiveContains true or false stating if the live person was genuinely present, i.e., not a Presentation Attack.
Check if there is a detection event of a potential counterfeit document.Document.Data.BarcodeSecurityContains PASS or FAIL and indicates a potentially counterfeit document. This key is only present for documents with PDF417 barcode.
Check if there are significant discrepancies between OCR and machine-readable information such as MRZ and barcode(s).Document.Data.mismatchMrzOcrThis key is present and set to true only if there is a substantial difference between document machine-readable data and OCR data. Otherwise, there is no key (null).
Check if there are any signals from the document manipulation detection AI stack (screen replay/paper copy / etc.).Document.Data.padResultContains PASS or FAIL and indicates potential document manipulation, for example, the Screen Replay attack. The details of AI pipelines for document manipulation can be found in Document.RawData array, in  Ipsidy.Bus.Pad.Score key.

Proof Results Suggested Decision Matrix​

The following table suggests the application logic to determine if the user must be allowed to proceed with enrollment/onboarding.

🚧

Developers Must Impletment Decision Logic

authID does not provide an automatic decions based on the outputs of signals from the Proof process. Developers must code their own decision logic that properly accounts for failed signals that indicate fraud.

ParameterDocument Type​ValueAction
MatchedAllfalseReject
LivenessDetectionResult.IsLiveAllfalseReject
Document.Data.BarcodeSecurityDriver License / State IDFAILReject
Document.Data.mismatchMrzOcrAlltrueManual Review or Reject
Document.Data.padResultAllFAILManual Review or Reject