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.
| Property | Description | Contains | When this is populated? | Extracted Info |
|---|---|---|---|---|
| scannedValues | Values extracted from the Document.* | The extracted and organized data of the Document. | Always. | First Name, Last Name, etc. |
| userConfirmedValues | Values 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. |
| barcodeValues | Values 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.*** |
| barcode2Values | Values 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.*** |
| nfcValues | Values 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.*** |
| mrzValues | Values 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. |
| templateInfo | Values 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.
| groupKey | Description |
|---|---|
| userInfo | Information related to the Document Holder (First Name, Last Name, Date of Birth, etc.). |
| idInfo | Information about the Document itself (ID Number, Country Code, Date of Expiration, etc). |
| addressInfo | Information related to the Document Holder's Address (City, Country, ZIP Code, etc.). |
| secondaryUserInfo | Information related to the Document Holder's Physical Characteristics or Traits (Height, Weight, Eye Color, etc.). |
| customFields | Information 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.
| groupKey | fieldKey | Description |
|---|---|---|
| userInfo | firstName | First Name of the Document Holder. |
| userInfo | middleInitial | Middle Initial of the Document Holder. |
| userInfo | middleName | Middle Name of the Document Holder. |
| userInfo | lastName | Last Name of the Document Holder. |
| userInfo | fullName | Full Name of the Document Holder. |
| userInfo | givenName | Given Name/Preferred Name of the Document Holder. |
| userInfo | dateOfBirth | Date of Birth of the Document Holder. |
| userInfo | placeOfBirth | Place of Birth of the Document Holder. |
| userInfo | placeOfBirthLine2 | Line 2 of the Place of Birth. |
| userInfo | nationality | Nationality of the ID Holder. |
| userInfo | employer | Employer of the ID Holder. |
| userInfo | profession | Profession of the ID Holder. |
| userInfo | fatherFirstName | First Name of the ID Holder's Father. |
| userInfo | fatherlastname | Last Name of the ID Holder's Father. |
| userInfo | motherFirstName | First Name of the ID Holder's Mother. |
| userInfo | motherLastName | Last Name of the ID Holder's Mother. |
| userInfo | grandfatherFirstName | First Name of the ID Holder's Grandfather. |
| idInfo | idNumber | ID Number of the Document. |
| idInfo | idNumber2 | Line 2 of the ID Number. |
| idInfo | bookletNumber | Booklet Number of the Document. |
| idInfo | issuingAuthority | Issuing Authority for the Document. |
| idInfo | authorityLine2 | Line 2 of the Issuing Authority for the Document. |
| idInfo | placeOfIssue | Location of where the Document was issued by the Issuing Authority. |
| idInfo | dateOfIssue | Date the Document was issued by the Issuing Authority. |
| idInfo | permitValidFrom | Date the Permit is valid from. |
| idInfo | dateOfExpiration | Date the Document is no longer considered valid by the Issuing Authority. |
| idInfo | class | Classification of the Document (e.g. California Driver License of Class A, B, or C). |
| idInfo | end | Endorsements that provide the Document Holder with extra driving privileges (e.g. permission to drive a School Bus). |
| idInfo | restrictions | Restrictions that a Document Holder must follow while driving (e.g. Correct Lenses must be worn). |
| idInfo | passportType | Type of Passport (if the Document is a Passport). |
| idInfo | countryCode | Country Code of the Document. |
| idInfo | civilStatus | Married/Civil Status of the ID Holder. |
| idInfo | barcode | Barcode of the Document. |
| idInfo | mrzLine1 | MRZ Line 1 of the Document. |
| idInfo | mrzLine2 | MRZ Line 2 of the Document. |
| idInfo | mrzLine3 | MRZ Line 3 of the Document. |
| addressInfo | address1 | Line 1 of the Street Address of the Document Holder. |
| addressInfo | address2 | Line 2 of the Street Address of the Document Holder. |
| addressInfo | address3 | Line 3 of the Street Address of the Document Holder. |
| addressInfo | addressLine4 | Line 4 of the Street Address of the Document Holder. |
| addressInfo | city | City where the Document Holder resides. |
| addressInfo | state | State where the Document Holder resides. |
| addressInfo | zipcode | ZIP Code of the area where the Document Holder resides. |
| addressInfo | country | Country where the Document Holder resides. |
| addressInfo | province | Province where the Document Holder resides. |
| addressInfo | territory | Territory where the Document Holder resides. |
| secondaryUserInfo | eyes | Eye Color of the Document Holder. |
| secondaryUserInfo | hair | Hair Color of the Document Holder. |
| secondaryUserInfo | height | Body Height of the Document Holder. |
| secondaryUserInfo | weight | Body Weight of the Document Holder. |
| secondaryUserInfo | sex | Sex/Gender of the Document Holder. |
| secondaryUserInfo | bloodType | Blood Type of the Document Holder. |
| customFields | customField1 | Custom Field Value that varies by OCR Template. |
| customFields | customField2 | Custom Field Value that varies by OCR Template. |
| customFields | customField3 | Custom Field Value that varies by OCR Template. |
| customFields | customField4 | Custom Field Value that varies by OCR Template. |
| customFields | customField5 | Custom 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"
}
}