Guides
Home

OCR Match Details

Applies to Direct | Capture

Suggest Edits

When you include the ocr_match signal in the /start request body, we perform OCR matching checks between the image and the extracted barcode or MRZ data. Match results are returned in the /get-results response as part of an ocr_match object. The ocr_match object contains the matching results for data fields found on the ID document, such as the name, document number, country code, expiration date, and so on. For each field, the matching result is determined by a similarity score and a similarity threshold.

  • The similarity score (from 0 to 100) is a confidence estimate that the image matched the barcode or the MRZ data.
  • The similarity threshold is a cutoff value, for example, 70. In that case, a match is reported only if the similarity score is 70 or greater. If not, a mismatch is reported.

👍

Your own circumstances and use cases will impact our matching results. Similarity scores, thresholds, and results are simply recommendations provided for convenience. You must use the information we provide to make your own determination of a matching result, regardless of whether we report a match or a mismatch.

Example responses

By way of example, consider isNameMatch and nameMatchDetails.

Exact match response

This example response illustrates an exact match.

{
  "isNameMatch": true,
  "nameMatchDetails": {
    "similarityThreshold": 70,
    "similarityScore": 100,
    "details": "Exact match between barcode and front data
}

If similarityScore is 100, then isNameMatch is true.

Match with slight discrepancy response

👍

A nearly exact match is considered a match with a slight discrepancy. Just as a human being can tell the difference between different objects that mean the same thing, OCR matching determines if the two fields are nearly exact despite a slight discrepancy. Discrepancies are often caused by factors that affect photo quality: blur, obscurity, shadow, and glare.

This example response illustrates a match with slight discrepancy.

{
  "isNameMatch": true,
  "nameMatchDetails": {
    "similarityThreshold": 70,
    "similarityScore": 90,
    "details": "Considered match with slight discrepancy in either barcode and/or front data"
  }
}

If similarityThreshold is 70 and similarityScore is between 70 and 99, then isNameMatch is true.

Mismatch response

This example response illustrates a mismatch.

{
  "isNameMatch": false,
  "nameMatchDetails": {
    "similarityThreshold": 70,
    "similarityScore": 10,
    "details": "Similarity score is lower than similarity threshold"
  }
}

If similarityThreshold is 70 and similarityScore is between 0 and 69, then isNameMatch is false.

Compared data fields

The ocr_match response contains comparison results for the following data fields.

  • Issuer
  • Document Number
  • Name
  • Address
  • Date of Birth
  • Country Code
  • Nationality
  • Height
  • Weight
  • Eye Color
  • Sex
  • Issue Date
  • Expiration Date
  • Driver License Class
  • Driver License Endorsement
  • Driver License Restrictions
  • Real ID

Understanding null values

To perform the comparison for a specific data field, that data field must be found in both the OCR text and the barcode or MRZ. If the data field is not found, then null is returned for that data field in the ocr_match response.

Here is sample response data showing driver license class comparison results. A null value is returned for isDlClassMatch and similarityScore. This means a comparison is not possible.

{
  "isDlClassMatch": null,
  "dlclassMatchDetails": {
            "similarityScore": null,
            "similarityThreshold": 70,
            "details": "Missing value for comparison"
          }
}

A null value can be due to several factors:

  • DL class was not found in OCR text. This might be the result of poor image quality (for example, glare).
  • DL class was not found in barcode data. This might be the result of unencoded data. Not all jurisdictions encode DL class in the barcode.

Comparison sources and null values

In the /get-results response, you can investigate other response objects:

  • OCR contains image text.
  • idcheck contains barcode data.
  • extendedId contains MRZ data.

Investigating these objects can help you to determine whether the data fields used for comparison were found or not found.

For example, the dlClass property of the OCR object and the driverClass property of the idcheck object must both be available for a successful comparison. Here is sample response data showing those properties. 

{
  "OCR": {
    "data": {
      "dlClass": "D",
    }
  },
  
  "idcheck": {
    "data": {
      "driverClass": "",
    }
  }
}

Notice that "dlClass": "D" is returned in the OCR response but "driverClass": "" is returned in the idcheck response. The driverClass is not found in the barcode. Therefore, a comparison is not possible, and null values are returned in the ocr_match response.

👍

Investigate /get-results response objects to find OCR comparison data fields. You can often determine why null values are returned in the ocr_match response.

Match result messages

Match results are described by a message returned in details.

Exact match message

When there is an exact match, details returns one of the following messages depending on the document type:

  • "Exact match between barcode and front data."
  • "Exact match between mrz and front data."

This accompanies a similarityScore of 100.

{  
  "nameMatchDetails": {  
    "similarityThreshold": 70,  
    "similarityScore": 100,  
    "details": "Exact match between barcode and front data"  
  }  
}

👍

In the case of a passport or international ID document, the message specifies mrz instead of barcode.

Nearly exact match message

When there is a nearly exact match, details returns one of the following messages depending on the document type:

  • "Considered match with slight discrepancy in either barcode and/or front data."
  • "Considered match with slight discrepancy in either mrz and/or front data."

This message accompanies a similarityScore between the similarityThreshold and 99. 

{
  "nameMatchDetails": {
    "similarityThreshold": 70,
    "similarityScore": 90,
    "details": "Considered match with slight discrepancy in either barcode and/or front data"
  }
}

Mismatch message

When there is a mismatch, details returns the following message:

  • "Similarity score is lower than similarity threshold."

This message accompanies a similarityScore less than similarityThreshold.

{
  "nameMatchDetails": {
    "similarityThreshold": 70,
    "similarityScore": 10,
    "details": "Similarity score is lower than similarity threshold"
  }
}

Missing value (null) message

When there is a missing value, details returns the following message:

  • "Missing value for comparison."

This message accompanies a similarityScore of null.

{
  "nameMatchDetails": {
    "similarityThreshold": 70,
    "similarityScore": null,
    "details": "Missing value for comparison"
  }
}

Updated 2 days ago