Querying OCR, Barcode & NFC Data from the documentData JSON

Overview

The documentData object contains the results of an OCR or ID Scan, while holding additional data for NFC and Barcode scenarios. The documentData object is returned as a property in both the ID Scan Only Result Object and the 3D:2D Photo ID Matching Result Object.

For the usage of documentData in "No Template" mode, see Universal Photo ID (No Template) Mode.

Properties

The ID Scan Results are stored in different properties of the documentData object.

PropertyDescriptionContainsWhen this is populated?Extracted Info
scannedValuesValues extracted from the Document.*The extracted and organized data of the Document.Always.First Name, Last Name, etc.
userConfirmedValuesValues submitted by the User through the User Confirmation Page.**

All field results will be returned in this property (not just the ones modified by the User).
Only the organized data after User Confirmation (including any User-modified data). The ID Scan performs the User Confirmation Step.Not Applicable.
barcodeValuesValues that were scanned from the First Barcode.The Raw Data and, if supported by the FaceTec SDKs, the Extracted and Organized data from the Document's First Barcode.Document possesses a Barcode, the OCR Template requests it, and the barcode is successfully scanned.First Name, Last Name, etc.***
barcode2ValuesValues that were scanned from the Second Barcode.The Raw Data and, if supported by the FaceTec SDKs, the Extracted and Organized data from the Document's Second Barcode.Document possesses a Second Barcode, the OCR Template requests it, and the Second Barcode is successfully scanned.First Name, Last Name, etc.***
nfcValuesValues that were extracted from the NFC Chip.The Raw Data, certificate signing information, and the extracted and organized data of the Document from the NFC chip.Document possesses an NFC chip, the OCR Template requests it, and NFC is successfully scanned.First Name, Last Name, Signing Certificate, etc.***
mrzValuesValues that were extracted from the MRZ.The extracted and organized data of the Document from the MRZ.Document possesses an MRZ, the OCR Template has marked the MRZ, and the MRZ is successfully scanned.First Name, Last Name, etc.
templateInfoValues that have information about the OCR Template.The Country of the Document (documentCountry), the State of the Document (documentState), the OCR Template Name (templateName), and the Document Type (templateType), as specified in the OCR Template Creator.Always.Not Applicable.

* For each field in scannedValues, an analysis is made that considers all extracted sources (OCR, MRZ, NFC and Barcode). The analysis is done by validating each result with the expected data format, while also weighing it against the results from MRZ, NFC or Barcode, which have a higher probability of being correct. If the MRZ Results are used to override the original OCR Results, then nonMRZValue will store the original OCR Value.

** If User Confirmation is skipped, then the documentData object will not contain userConfirmedValues.

*** The extractedInfo field is special for barcodeValues, barcode2Values, and nfcValues. For these cases, the extractedInfo field contains the "raw" data (key/value pairs) that was lifted from the Barcode or NFC Scan. FaceTec has created some internal/private NFC and Barcode parsers that attempt to get structured data from the NFC or Barcode scan, but these parsers are not guaranteed to work for all Document Types that exist. We provide the extractedInfo property so that the Barcode or NFC data can be parsed by Developers based on their knowledge of the specific formats they are using.

Group Keys

Within the properties of the documentData Object, values are further separated into a Group Structure. A group can be identified by its groupKey.

groupKeyDescription
userInfoInformation related to the Document Holder (First Name, Last Name, Date of Birth, etc.).
idInfoInformation about the Document itself (ID Number, Country Code, Date of Expiration, etc).
addressInfoInformation related to the Document Holder's Address (City, Country, ZIP Code, etc.).
secondaryUserInfoInformation related to the Document Holder's Physical Characteristics or Traits (Height, Weight, Eye Color, etc.).
customFieldsInformation that does not neatly belong into any of the other groups.

Field Keys

Each specific value within a group is specified as a field. A field can be identified by its fieldKey.

groupKeyfieldKeyDescription
userInfofirstNameFirst Name of the Document Holder.
userInfomiddleInitialMiddle Initial of the Document Holder.
userInfomiddleNameMiddle Name of the Document Holder.
userInfolastNameLast Name of the Document Holder.
userInfofullNameFull Name of the Document Holder.
userInfogivenNameGiven Name/Preferred Name of the Document Holder.
userInfodateOfBirthDate of Birth of the Document Holder.
userInfoplaceOfBirthPlace of Birth of the Document Holder.
userInfoplaceOfBirthLine2Line 2 of the Place of Birth.
userInfonationalityNationality of the ID Holder.
userInfoemployerEmployer of the ID Holder.
userInfoprofessionProfession of the ID Holder.
userInfofatherFirstNameFirst Name of the ID Holder's Father.
userInfofatherlastnameLast Name of the ID Holder's Father.
userInfomotherFirstNameFirst Name of the ID Holder's Mother.
userInfomotherLastNameLast Name of the ID Holder's Mother.
userInfograndfatherFirstNameFirst Name of the ID Holder's Grandfather.
idInfoidNumberID Number of the Document.
idInfoidNumber2Line 2 of the ID Number.
idInfobookletNumberBooklet Number of the Document.
idInfoissuingAuthorityIssuing Authority for the Document.
idInfoauthorityLine2Line 2 of the Issuing Authority for the Document.
idInfoplaceOfIssueLocation of where the Document was issued by the Issuing Authority.
idInfodateOfIssueDate the Document was issued by the Issuing Authority.
idInfopermitValidFromDate the Permit is valid from.
idInfodateOfExpirationDate the Document is no longer considered valid by the Issuing Authority.
idInfoclassClassification of the Document (e.g. California Driver License of Class A, B, or C).
idInfoendEndorsements that provide the Document Holder with extra driving privileges (e.g. permission to drive a School Bus).
idInforestrictionsRestrictions that a Document Holder must follow while driving (e.g. Correct Lenses must be worn).
idInfopassportTypeType of Passport (if the Document is a Passport).
idInfocountryCodeCountry Code of the Document.
idInfocivilStatusMarried/Civil Status of the ID Holder.
idInfobarcodeBarcode of the Document.
idInfomrzLine1MRZ Line 1 of the Document.
idInfomrzLine2MRZ Line 2 of the Document.
idInfomrzLine3MRZ Line 3 of the Document.
addressInfoaddress1Line 1 of the Street Address of the Document Holder.
addressInfoaddress2Line 2 of the Street Address of the Document Holder.
addressInfoaddress3Line 3 of the Street Address of the Document Holder.
addressInfoaddressLine4Line 4 of the Street Address of the Document Holder.
addressInfocityCity where the Document Holder resides.
addressInfostateState where the Document Holder resides.
addressInfozipcodeZIP Code of the area where the Document Holder resides.
addressInfocountryCountry where the Document Holder resides.
addressInfoprovinceProvince where the Document Holder resides.
addressInfoterritoryTerritory where the Document Holder resides.
secondaryUserInfoeyesEye Color of the Document Holder.
secondaryUserInfohairHair Color of the Document Holder.
secondaryUserInfoheightBody Height of the Document Holder.
secondaryUserInfoweightBody Weight of the Document Holder.
secondaryUserInfosexSex/Gender of the Document Holder.
secondaryUserInfobloodTypeBlood Type of the Document Holder.
customFieldscustomField1Custom Field Value that varies by OCR Template.
customFieldscustomField2Custom Field Value that varies by OCR Template.
customFieldscustomField3Custom Field Value that varies by OCR Template.
customFieldscustomField4Custom Field Value that varies by OCR Template.
customFieldscustomField5Custom Field Value that varies by OCR Template.

Example documentData Object

{
  "nfcValues": {
    "extractedInfo": {
      "signingCertificate": "VALUE_SCANNED_FROM_NFC_CHIP",
      "wasSignedDataValidated": true,
      "mrzData": "VALUE_SCANNED_FROM_NFC_CHIP",
      "placeOfBirth": "VALUE_SCANNED_FROM_NFC_CHIP",

      // FaceTec Note:  This could contain other values we extract from the MRZ and NFC Chip

    },
    "rawData": {
      "DG1": "...",
      "DG14": "...",
      "DG15": "...",
      "DG2": "...",
      "SOD": "..."
    },

    // FaceTec Note:  nfcValues are put in the groups structure from OCR Template Creator

    "groups": [ 
      {
        "fields": [
          {
            "fieldKey": "placeOfBirth",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_NFC_CHIP"
          },
          
          // FaceTec Note:  More fields will appear here depending on the OCR Template

        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      },

      // FaceTec Note:  More groups will appear here depending on the OCR Template
      
    ]
  },
  "barcodeValues": {
    "extractedInfo": {
      "firstName": "VALUE_SCANNED_FROM_BARCODE",
      
      // FaceTec Note:  More fields can appear here based on extraction from the rawData

    },
    "rawData": "raw string read from the First Barcode",

    // FaceTec Note:  barcodeValues are put in the groups structure from OCR Template Creator

    "groups": [ 
      {
        "fields": [
          {
            "fieldKey": "placeOfBirth",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_BARCODE"
          },
          
          // FaceTec Note:  More fields will appear here depending on the OCR Template

        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      },
      
      // FaceTec Note:  More groups will appear here depending on the OCR Template

    ]
  },
  "barcode2Values": {
    "extractedInfo": {
      "firstName": "VALUE_SCANNED_FROM_BARCODE",
      
      // FaceTec Note:  More fields can appear here based on extraction from the rawData

    },
    "rawData": "raw string read from the Second Barcode",

    // FaceTec Note:  barcode2Values are put in the groups structure from OCR Template Creator

    "groups": [ 
      {
        "fields": [
          {
            "fieldKey": "placeOfBirth",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_BARCODE"
          },
          
          // FaceTec Note:  More fields will appear here depending on the OCR Template

        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      },
      
      // FaceTec Note:  More groups will appear here depending on the OCR Template

    ]
  },
  "mrzValues": { // values read from MRZ and put into the groups structure we have in OCRTemplate (IDTC)
    "groups": [
      {
        "fields": [
          {
            "fieldKey": "firstName",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_MRZ"
          }
        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      }
    ]
  },

  // FaceTec Note:  These are the highest confidence answers that could be extracted from the ID Scan.  
  // Data from the NFC, Barcode, or MRZ will be preferred.

  "scannedValues": { 
    "groups": [
      {
        "fields": [
          {
            "fieldKey": "firstName",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_PHOTO_ID"
          },
          {
            "fieldKey": "lastName",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_SCANNED_FROM_MRZ",
            "nonMRZValue": "VALUE_SCANNED_FROM_PHOTO_ID"
          },
          {
            "fieldKey": "dateOfBirth",
            "uiFieldType": "FORMAT_DEFINED_IN_IDTC",
            "value": "VALUE_SCANNED_FROM_PHOTO_ID"
          },
          
          // FaceTec Note:  More fields will appear here depending on the OCR Template

        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      },
      
      // FaceTec Note:  More groups will appear here depending on the OCR Template

    ]
  },
  "userConfirmedValues": {
    "groups": [
      {
        "fields": [
          {
            "fieldKey": "firstName",
            "uiFieldType": "Alphabetic",
            "value": "VALUE_ENTERED_ON_USER_CONFIRMED"
          }
        ],
        "groupFriendlyName": "Your Information",
        "groupKey": "userInfo"
      }
    ]
  },
  "templateInfo": {
    "documentCountry": "COUNTRY_NAME",
    "documentState": "STATE_NAME",
    "templateName": "TEMPLATE_NAME",
    "templateType": "TEMPLATE_TYPE"
  }
}

Universal Photo ID (No Template) Mode

When in Universal Photo ID (No Template) mode, the documentData object will only contain scannedValues and templateInfo. The scannedValues property will be formatted differently than in the normal (Template Detection) mode. The templateInfo property will have a documentCountry, documentState, templateName, and templateType of "UNSET".

{
  "scannedValues": { 
    "rawData": [
      {
        
        // FaceTec Note:  "front" Object will contain an array with OCR reading and text coordinates of all Text found on the Front of the ID
        
        "front": [
          {
            "ocrDetectedRect": [
              0,   // X Coordinate of the Top-left corner
              0,   // Y Coordinate of the Top-left corner
              100, // Width
              100  // Height
            ],
            "scannedValue": "VALUE_SCANNED_FROM_PHOTO_ID"
          }
          
          // FaceTec Note:  More objects will appear here depending on the scanned document

        ],

        // FaceTec Note:  "back" Object will contain an array with OCR reading and text coordinates of all Text found on the Back of the ID
     
        "back": [
          {
            "ocrDetectedRect": [
              0,   // X Coordinate of the Top-left corner
              0,   // Y Coordinate of the Top-left corner
              100, // Width
              100  // Height
            ],
            "scannedValue": "VALUE_SCANNED_FROM_PHOTO_ID"
          }
          
          // FaceTec Note:  More objects will appear here depending on the scanned document

        ]
      }
    ]
  },
  "templateInfo": {
    "documentCountry": "UNSET",
    "documentState": "UNSET",
    "templateName": "UNSET",
    "templateType": "UNSET"
  }
}