GovFaceMatch Technical Details

GovFaceMatch is Incode’s direct connection to state DMV systems for biometric face comparison. During verification, the supported document data fields are sent to the DMV. If the document data fields match to a record within the DMV database, the uploaded selfie is compared against the official portrait stored in the state’s DMV database. A successful Face Match guarantees that the Data Match also passed, and provides the highest level of assurance that the person presenting the document is the legitimate holder.

GovFaceMatch is part of the overall US GovMatch offering.

Decisioning

State requirements mandate that certain data fields must match before Incode can access the DMV selfie. Face matching only occurs after this data match succeeds. Therefore, a successful Face Match guarantees that the Data Match also passed.

Decisioning should be based on the status value in the overall object. The status value can be:

OK: Face Match is successful
FAIL: Face Match is unsuccessful
- Did not meet Must-Match requirements of the state
  
  OR
- Met Must-Match requirements of the state, but uploaded face image did not match official photograph stored in the state's DMV database

Scoring

Most states return a face match confidence score with a passing threshold of 77. Due to variability of image quality by state, face match confidence thresholds vary, and not every state may provide that level of granularity. Numeric match confidence is provided where applicable and acceptance thresholds are subject to change. When numeric match confidence is not returned, a simple pass (100.0) / fail (0.0) is used when determining a match.

Must-Match Data fields for CA

For California, the following data must meet the listed match requirements:

Document Number: Exact match
First 3 letters of Last Name: Partial match
Date of Birth: Exact match

Must-Match Data fields for GA, MS, VA

For Georgia, Mississippi, and Virginia, the following data must meet the listed match requirements:

Document Number: Exact match
First Name: Exact match
Last Name: Exact match
Date of Birth: Exact match

Standalone API

POST /omni/process/government-validation?countryCode=USA

To retrieve the results of GovMatch, use the Fetch Scores endpoint. When government record verification is enabled for your organization, a governmentValidation field is present in the endpoint results.

Request Body

{
    "idNumber": "T123456789",
    "firstName": "EMILYTEST",
    "paternalLastName": "DAVISTEST",
    "birthDate": "1987-04-18",
    "base64Image": "{{selfie}}",
    "issuerState": "VA"
}

Response Body

{
    "valid": true,
    "statusCode": 0,
    "governmentValidation": {
        "recognitionConfidence": {
            "value": "100.0",
            "status": "OK"
        },
        "validationStatus": {
            "value": "0",
            "status": "OK",
            "key": "ok"
        },
        "ocrValidation": [
            {
                "value": "true",
                "status": "OK",
                "key": "documentNumber"
            },
            {
                "value": "true",
                "status": "OK",
                "key": "firstName"
            },
            {
                "value": "true",
                "status": "OK",
                "key": "paternalLastName"
            },
            {
                "value": "true",
                "status": "OK",
                "key": "birthDate"
            }
        ],
        "ocrValidationOverall": {
            "value": "100.0",
            "status": "OK"
        },
        "overall": {
            "value": "100.0",
            "status": "OK"
        },
        "provider": "DMV Face Match"
    }
}

Response Details

The response for GovFaceMatch is contained within the governmentValidation object. This object contains the following fields:

Field	Type	Description
`validationStatus`	StatusValue	Provider status code for error handling. Contains a `value`, `status`, and `key`. See below for more information.
`ocrValidation` Optional	Array[StatusValue]	Individual data field match results. Each data field result contains a `value`, `status`, and `key`. See below for more information.
`recognitionConfidence` Optional	StatusValue	Face Match confidence score. Only present for GovFaceMatch; indicates biometric verification was performed. Contains a `value` and `status`. See below for more information.
`ocrValidationOverall` Optional	StatusValue	Percentage of OCR fields that matched. Supplementary data for analysis. Contains a `value` and `status`. See below for more information.
`overall`	StatusValue	Primary verification result. Use this field to determine pass/fail. Contains a `value` and `status`. See below for more information.
`provider` Optional	String	Indicates whether the request was sent to GovFaceMatch (`GovFaceMatch`) or GovDataMatch (`GovDataMatch`). Only present for US verification.

StatusValue key/value pairs

Any field listed as StatusValue in the table above contains a value and a status. Some also contain a key.

Field	Type	Description
`value` Optional	String	The numeric or boolean value.
`status`	String	The status code wrapped in a strong. Possible statuses are: `OK`: User passed verification. `FAIL`: Either data or face did not match during validation. `UNKNOWN`: GovFaceMatch was run, but the submitted document or region isn’t supported or something went wrong when trying to perform validation.
`key` Optional	String	The key for which the status is being reported. For example, `firstName`, `birthDate`, or `documentNumber`.

Error Codes

Please refer to Upcoming Changes to Error Codes for US Government Verification

If these errors appear for a legitimate user, or if the errors persist, submit a support ticket through http://support.incode.com/ for further investigation.

Reason Code	Description	Status	Next Steps
`providerNotConfigured`	Provider Not Configured Provider is not configured or is incorrectly configured for this flow.	`UNKNOWN`	Submit a support ticket through http://support.incode.com/ to troubleshoot issues with your configuration.
`missingDocumentId`	Missing Document Number Document number missing or has an invalid pattern.	`UNKNOWN`	Check ID capture quality for barcode/OCR readability issues.
`invalidExpirationDate`	Invalid Expiration Date Expiration date is not valid per document standards.	`UNKNOWN`	Check ID capture quality for barcode/OCR readability issues. If user is legitimate, submit a support ticket through http://support.incode.com/ for further investigation.
`notEnoughData`	Missing Required Data One or more required fields are missing or invalid.	`UNKNOWN`	Ensure all required fields are provided by user into session.
`missingSelfie`	Missing Selfie Provider requires selfie for processing but not provided in session.	`UNKNOWN`	Ensure the user provides a selfie into the session.
`selfieChecksFailed`	Selfie Image Quality Check Failed Higher-quality selfie needed for processing by provider.	`UNKNOWN`	Ensure the user retakes a higher-quality selfie (e.g. check brightness, blurriness, face mask, occlusion).
`documentTypeNotSupported`	Document Type Not Supported Invalid document type for validation by the configured provider.	`UNKNOWN`	Ensure the user is providing a supported document type.
`geographicRegionNotSupported`	Country Not Supported Document country not supported by the configured provider.	`UNKNOWN`	Verify the user is providing supported document and countries are provisioned correctly.
`geographicStateRegionNotSupported`	State Not Supported Document state not supported by the configured provider.	`UNKNOWN`	Verify the user is providing supported document and states are provisioned correctly.
`connectionError`	Provider Connection Error Error occurred during processing within provider environment.	`UNKNOWN`	Try again later; if issue persists, submit a support ticket through http://support.incode.com/.
`infrastructureError`	Incode Processing Error Error occurred during processing within Incode environment.	`UNKNOWN`	Try again later; if issue persists, submit a support ticket through http://support.incode.com/.
`null`	If government validation status is not present, then it means the module was not run.	`UNKNOWN`	Try again later; if issue persists, submit a support ticket through http://support.incode.com/.
`userNotFound`	User Not Found ID not found in government database.	`FAIL`	Check data extraction quality. If user is legitimate, submit a support ticket through http://support.incode.com/ for further investigation.
`faceComparisonFailed`	Face Match Failed Selfie does not match government database portrait.	`FAIL`	Check selfie capture quality. If user is legitimate, submit a support ticket through http://support.incode.com/ for further investigation.

Updated 1 day ago

Did this page help you?