---
title: "GovDataMatch Technical Details"
url: "https://developer.incode.com/general-reference/dmv-data-match-technical-details/"
section: "general-reference"
group: "Government Verification Sources / United States Govmatch"
version: "v1.1"
status: "live"
---
# DMV Data Match Technical Details


GovDataMatch is Incode's data verification service through AAMVA or through validation of Verifiable Credentials. During verification, the supported document data fields are validated against the data on the record held by the issuing state's DMV.

GovDataMatch is part of the overall [US GovMatch](/general-reference/united-states-govmatch/) offering.

GovDataMatch now runs on AAMVA's DLDV 3.0 service. This update improves the quality of the match and the detail in the response. The endpoint, the request body, the scoring model, and the provider value are unchanged.

## Decisioning

The document number is the anchor for the whole check. When the issuing agency confirms the document number, the remaining submitted fields are evaluated individually and returned in `ocrValidation`. When it does not, no field-level results are returned and the module resolves to one of the statuses in the [error table](#error-codes) below.

Each field is returned with its own result in `ocrValidation`:

| Key | Evaluated |
|---|---|
| `documentNumber` | Always. The anchor for the check. If it does not match, no other field is scored |
| `firstName` | Always |
| `paternalLastName` | Always |
| `birthDate` | Always |
| `issueDate` | Always, except in jurisdictions that cannot verify an issue date for the document class presented |
| `expirationDate` | Always. Replaced by an indefinite-expiration check where the credential carries no expiry |
| `address` | When address validation is enabled on the flow. Street line 1 |
| `addressLine2` | When address validation is enabled on the flow |
| `city` | When address validation is enabled on the flow |
| `state` | When address validation is enabled on the flow |
| `zipCode` | When address validation is enabled on the flow |

Not every jurisdiction supports every field. Talk to your account team to confirm coverage for the jurisdictions relevant to you.

### Elements the agency cannot answer

An element resolves three ways:

- It matches the agency record
- It does not match the agency record
- The issuing agency holds no record for it

Only the first two are scored. Where the agency holds no record for an element or cannot answer it, that element is **omitted from `ocrValidation`** rather than returned as a failure, and it applies no score deduction. This behavior leads to fewer deductions overall and a shorter `ocrValidation` array on sessions where the agency holds a partial record.

:::info
**Action for integrators.** If your decision logic counts entries in `ocrValidation`, or assumes a fixed set of keys, review it. The array varies in length by jurisdiction and by record completeness.
:::

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

* **OK**: Data Match is successful

* **FAIL**: Data Match is unsuccessful

<Accordion title="Scoring">
  The module score starts at 100. Each field returned as `FAIL` deducts points according to the severity configured for that check: 15 points at the default MEDIUM severity, less for the address fields, which are LOW. Elements the issuing agency could not answer are not counted as failures and apply no deduction.

  * **OK**: score above 55
  * **FAIL**: score of 55 or below, or every returned field failed

  Where the document number itself did not match, `ocrValidationOverall` and `overall` are both returned as `0.0` / `FAIL`.
</Accordion>

<Accordion title="NY Verifiable Credential" >
  GovDataMatch supports NY through the validation of the Verifiable Credential within the document. A successful Data Match confirms the document was issued by the New York Department of Motor Vehicles and the identity data in the barcode has not been altered or tampered with. Results are returned as OK (100.0) or FAIL (0.0).

Note: supports New York driver’s licenses and ID cards issued after 2005 
</Accordion>

## How data fields are matched

Name and address fields aren't compared character by character. The issuing agency runs several comparisons on each field and reports each one separately. Incode returns the field as a match if any comparison matched.



Comparisons include the exact value, phonetic variants, values within a small edit distance, and any alternative or former name the agency holds on record. This covers common spelling variants (`STEPHEN` and `STEVEN` match; `JONHSON` and `JOHNSON` match) as well as the many valid ways to write the same address (`APT 4B`, `#4B`, and `UNIT 4B` are treated as the same value; `ST` and `STREET` match).

This doesn't lower the standard. Genuinely different values still return `FAIL`. What it prevents is a mismatch caused only by spelling, punctuation, or formatting. Matching behavior isn't configurable.



Two things to know:

* **Nicknames only match when the agency has them on record.** `ROBERT` doesn't automatically match `BOB`, since the two are neither phonetically similar nor within a small edit distance.
* **First and last name are stricter than other fields.** Anything short of a match returns `FAIL` rather than being treated as unevaluated. That said, two failed name fields alone still leave the module above the pass threshold.

## Standalone API

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

### Request Body

```json
{
    "documentNumber": "D12345678",
    "firstName": "JOHNTEST",
    "paternalLastName": "DOETEST",
    "birthDate": "03-16-1990",
    "issueDate": "01-15-2020",
    "expirationDate": "01-15-2028",
    "issuerState": "TX"
}
```

### Response Body

```json
{
    "valid": true,
    "statusCode": 0,
    "governmentValidation": {
        "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"
            },
            {
                "value": "true",
                "status": "OK",
                "key": "issueDate"
            },
            {
                "value": "true",
                "status": "OK",
                "key": "expirationDate"
            }
        ],
        "credentialStatus": [
            {
                "status": "OK",
                "key": "nonCommercialDriverLicenseStatus"
            },
            {
                "status": "OK",
                "key": "indefiniteExpiration"
            }
        ],
        "ocrValidationOverall": {
            "value": "100.0",
            "status": "OK"
        },
        "overall": {
            "value": "100.0",
            "status": "OK"
        },
        "provider": "GOVDATAMATCH"
    }
}
```

### Response Details

The response for GovDataMatch 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](#statusvalue-keyvalue-pairs) for more information. |
| `ocrValidation`<br />_Optional_ | Array[StatusValue] | Individual data field match results. Each data field result contains a `value`, `status`, and `key`. See [below](#statusvalue-keyvalue-pairs) for more information. |
| `credentialStatus`<br />_Optional_ | Array[StatusValue] | Issuing agency verdicts on credential attributes that were submitted. Does not affect `overall`. See [Credential status](#credential-status). |
| `ocrValidationOverall`<br />_Optional_ | StatusValue | Percentage of OCR fields that matched. Supplementary data for analysis. Contains a `value` and `status`. See [below](#statusvalue-keyvalue-pairs) for more information. |
| `overall` | StatusValue | Primary verification result. Use this field to determine pass/fail. Contains a `value` and `status`. See [below](#statusvalue-keyvalue-pairs) for more information. |
| `provider`<br />_Optional_ | String | Indicates whether the request was sent to GovFaceMatch (`GOVFACEMATCH`) or GovDataMatch (`GOVDATAMATCH`). Only present for US verification. |

#### StatusValue key/value pairs

This object contains the following fields:

| Field | Type | Description |
|---|---|---|
| `value`<br />_Optional_ | String | The numeric or boolean value. |
| `status` | String | The status code. Possible statuses are:<br /><br />- `OK`: User passed verification.<br />- `FAIL`: Data did not match during validation.<br />- `UNKNOWN`: GovDataMatch was run, but the submitted document or region isn't supported or something went wrong when trying to perform validation. |
| `key`<br />_Optional_ | String | The key for which the status is being reported. For example, `firstName`, `birthDate`, or `documentNumber`. |

### Credential status

The issuing agency reports verdicts on certain credential attributes. There is a `credentialStatus` array on the `governmentValidation` object if the session collected one of the attributes:

- **`nonCommercialDriverLicenseStatus`.** Whether the holder has a current, valid base driving privilege for standard passenger vehicles such as cars, vans, pickups, and SUVs. This attribute says nothing about commercial driver licenses; no CDL information is carried at any point, and a holder may also hold a CDL. Not every jurisdiction participates; where one doesn't, the status is `UNKNOWN`, not `FAIL`. Participation is expanding over time.

- **`indefiniteExpiration`.** Whether the credential is one of those issued with no expiration date. A small number of jurisdictions do this, in some cases only above a given age. When a credential is submitted as indefinite, the agency confirms that against its record and the verdict is returned both here and as the `expirationDate` row in `ocrValidation`. An expiration date and an indefinite indicator are mutually exclusive, so a credential carries one or the other, never both.

Each entry has a `key` and a `status` of `OK`, `FAIL`, or `UNKNOWN`. Verdicts are reported separately from `ocrValidation` because they describe the credential rather than verify a submitted value, so they don't affect `ocrValidationOverall` or `overall`.

### Error Codes

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

| Reason Code                         | Description                                                                                                                                          | Status    | Next Steps                                                                                                                                                                                                  |
| :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `providerNotConfigured`             | **Provider Not Configured**<br />Provider is not configured or is incorrectly configured for this flow.                                                   | `UNKNOWN` | Submit a support ticket through [http://support.incode.com/](http://support.incode.com/) to troubleshoot issues with your configuration.                                                                    |
| `missingDocumentId`                 | **Missing Document Number**<br />Document number missing or has an invalid pattern.                                                                       | `UNKNOWN` | Check ID capture quality for barcode/OCR readability issues.                                                                                                                                                |
| `invalidExpirationDate`             | **Invalid Expiration Date**<br />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/](http://support.incode.com/) for further investigation.     |
| `notEnoughData` | **Missing Required Data**<br />One or more required fields are missing or invalid, or the issuing agency could not evaluate the document number. | `UNKNOWN` | Ensure all required fields are provided by user into session. |
| `documentTypeNotSupported`          | **Document Type Not Supported**<br />Invalid document type for validation by the configured provider.                                                     | `UNKNOWN` | Ensure the user is providing a supported document type.                                                                                                                                                     |
| `geographicRegionNotSupported`      | **Country Not Supported**<br />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**<br />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**<br />Error occurred during processing within provider environment.                                                     | `UNKNOWN` | Try again later; if issue persists, submit a support ticket through [http://support.incode.com/](http://support.incode.com/).                                                                               |
| `infrastructureError`               | **Incode Processing Error**<br />Error occurred during processing within Incode environment.                                                         | `UNKNOWN` | Try again later; if issue persists, submit a support ticket through [http://support.incode.com/](http://support.incode.com/).                                                                               |
| `transactionLimitReached` | **Transaction Limit Reached**<br />The provider rejected the request because a rate or volume limit was exceeded. | `UNKNOWN` | Retry after a short delay. If the error persists, submit a support ticket through [http://support.incode.com/](http://support.incode.com/) so the limit can be reviewed. |
| `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/](http://support.incode.com/).                                                                               |
| `userNotFound` | **User Not Found**<br />The document number did not match, and no other submitted identity field matched the agency record. | `FAIL` | Check data extraction quality. If user is legitimate, submit a support ticket through [http://support.incode.com/](http://support.incode.com/) for further investigation. |
| `documentNumberMismatch` | **Document Number Mismatch**<br />The document number did not match, but other submitted identity fields did, so a record for this person exists under a different credential number. Commonly a renewed or replaced credential. | `FAIL` | Check data extraction quality. If user is legitimate, ask that a newer identity document is used for verification or submit a support ticket through [http://support.incode.com/](http://support.incode.com/) for further investigation. |