# Fetch OCR Data ## What is OCR data? Optical Character Recognition (OCR) data for an onboarding contains all information extracted from the ID document during the session. This includes both text information and available barcode or machine-readable zone (MRZ) data read and decoded from the back of the ID. > 📘 Different documents, different data > > Data in ID documents can vary widely. Therefore, this endpoint's response is dynamic. It will only contain the information relevant to the detected ID. If you use compiled languages (like Java or C#) to consume these endpoint responses, be aware that your JSON parsers could break if a property you expect is missing. ### How can I fetch OCR data? To fetch OCR data for a given onboarding session, you should always pass the session's unique interview ID, also called the Session ID, to the [fetch ocr data](ref:getocrdata) API endpoint. You can also test this endpoint at the preceding link. If you do not pass the interview ID, Incode attempts to extract it from the session token. ## Common use cases ### To extract information from the ID document attached to session The following sample shows some of the most commonly used OCR fields from the ID document. It is not a complete list, since the fields vary from document to document. A longer JSON response example with additional fields is at the end of this article. ```json JSON { "name": { "fullName": "", "firstName": "", "paternalLastName": "", "maternalLastName": "", // Optional "givenName": "", "middleName": "", // Optional "nameSuffix": "", // Optional "machineReadableFullName": "", // Optional, full name from Barcode or MRZ "givenNameMrz": "", // Optional "lastNameMrz": "" // Optional }, "address": "", // Optional, address as read from ID "addressFields": { "street": "", // Optional "colony": "", // Optional, not applicable for all countries "postalCode": "", // Optional "city": "", // Optional "state": "" // Optional }, "typeOfId": "", // Id classification, ie: Drivers License, Voter Identification, etc. "issuedAt": 0, // Issue date, expressed as a epoch timestamp in milliseconds "expireAt": 0, // Expiration date, expressed as a epoch timestamp in milliseconds "issuingCountry": "", // Optional "documentNumber": "", // Optional "fullAddress": true, //Optional. True if address from id is full (has three lines) "cic": "", // Mexican INE only "ocr": "", // Mexican INE only } ``` ### To extract information from the POA document attached to session When you need to extract the address or information from a POA document added to a session, you can access these fields in the JSON response: ```json JSON { "documentType": "", // Classifier of the provided POA document "poaName": "", // The name that appears in the provided POA document "addressStatementEmissionDate": "", // Expiration date, expressed as a epoch timestamp in milliseconds "addressFromStatement": "", // Full address read from statement "addressFieldsFromStatement": { "street": "", "colony": "", "postalCode": "", "city": "", "state": "" }, } ``` These fields should be enough to answer questions like: * What's the address in the POA document? * What name appears in the POA document? * When was the POA document issued? * What kind of document was used as POA? ## Other OCR data extraction endpoints The preceding samples come from the standard [ocr data](ref:getocrdata) endpoint. Incode offers three alternative endpoints for OCR data extraction, although these are less likely to be needed: 1. [OCR data v2](ref:getocrdatav2) wraps the response from the `ocr-data` endpoint under an `ocrData` field. It returns the same data as [ocr data](ref:getocrdata) endpoint. 2. [Second Id's OCR data](ref:getocrdatasecondid) is required if your flow is configured to have two ID documents attached to the same session. This will provide you with OCR data from the second ID. 3. [Batch fetch OCR data](ref:fetchbatchocr) can be used when you want to fetch OCR data for multiple onboarding sessions. > 📘 Scores and OCR Data > > OCR data shows in the Incode Dashboard along with some scoring. This scoring relates solely to the level of confidence on the data extracted from the captured image of the ID. Level of confidence for OCR data does not directly affect or alter the score of a session. ## Sample JSON File {/* ## Sample Response ```json JSON { "name": { "fullName": "Johnny Honeycrisp Appleseed", "machineReadableFullName": "JOHNNY HONEYCRISP APPLESEED", "firstName": "JOHNNY", "middleName": "HONEYCRISP", "givenName": "JOHNNY HONEYCRISOP", "paternalLastName": "APPLESEED" }, "address": "123 APPLE ORCHARD WAY SAN FRANCISCO CA 94105 USA", "addressFields": { "street": "123 APPLE ORCHARD WAY", "postalCode": "94105", "city": "SAN FRANCISCO", "state": "CA" }, "checkedAddress": "123 Apple Orchard Way, San Francisco, CA 94105, United States", "checkedAddressBean": { "postalCode": "94105", "city": "SAN FRANCISCO", "state": "CA", "label": "123 Apple Orchard Way, San Francisco, CA 94105, United States", "latitude": 31.64339, "longitude": -100.53304, "zipColonyOptions": [] }, "typeOfId": "DriversLicense", "documentFrontSubtype": "DRIVERS_LICENSE", "documentBackSubtype": "DRIVERS_LICENSE", "birthDate": 643112700000, "gender": "M", "documentNumber": "123456789", "refNumber": "1234567", "issuedAt": "1423136000000", "expireAt": "1293248000000", "expirationDate": 2030, "issueDate": 2023, "issuingCountry": "USA", "issuingState": "CALIFORNIA", "height": "084 IN", "weight": "225", "eyeColor": "BLU", "hairColor": "BLN", "classes": "R", "mentions": "NONE", "restrictions": "NONE", "fullNameMrz": "JOHNNY HONEYCRISP APPLESEED", "barcodeRawData": "@\n\u001e\rIANRS 1234567899794237948792DL987349234\nDCSAPPLESEED\n...", "ocrDataConfidence": { "birthDateConfidence": 1.0, "nameConfidence": 1.0, "givenNameConfidence": 1.0, "firstNameConfidence": 1.0, "middleNameConfidence": 1.0, "fathersSurnameConfidence": 1.0, "fullNameMrzConfidence": 1.0, "addressConfidence": 1.0, "streetConfidence": 1.0, "postalCodeConfidence": 1.0, "cityConfidence": 1.0, "stateConfidence": 1.0, "countryCodeConfidence": 1.0, "genderConfidence": 1.0, "issueDateConfidence": 1.0, "expirationDateConfidence": 1.0, "issuedAtConfidence": 1.0, "expireAtConfidence": 1.0, "documentNumberConfidence": 1.0, "heightConfidence": 1.0, "eyeColorConfidence": 1.0, "classesConfidence": 1.0, "mentionsConfidence": 1.0, "refNumberConfidence": 1.0, "weightConfidence": 1.0, "hairConfidence": 1.0, "restrictionsConfidence": 1.0 } } ``` ## Response Descriptions The response payload is composed of subsections. See below for descriptions of each property. 1. name: Structure which contains: 1. fullName: String. 2. firstName: String. 3. paternalLastName: String. 4. maternalLastName: String. Optional. 5. givenName: String. 6. middleName: String. Optional. 7. nameSuffix: String. Optional. 8. machineReadableFullName: String. Optional. Full name from Barcode or MRZ. 9. givenNameMrz: String. Optional. 10. lastNameMrz: String. Optional. 2. address: String. Optional. Address as read from id. Address can have one, two or three lines. In case of multiple lines, they are separated by \\n. 3. addressFields: Structure with following fields: 1. street: String. Optional. Street line in the way it is read from address string. 2. colony: String. Optional. Colony line the way it is read from address string. (Not applicable for all countries) 3. postalCode: String. Optional. Postal code in the way it is read from address string. 4. city: String. Optional. City in the way it is read from address string. 5. state: String. Optional. State in the way it is read from address string. 4. fullAddress : Boolean. This field is set to true if address from id is full (has three lines) or not. 5. invalidAddress : Boolean. Optional. This field cheks for a valid street, numeric postal code with 5 digits, and tha both colony and city have values. (Only checked for Mexican IDs) 6. checkedAddress: String. Optional. Address as obtained after processing with geocoder geolocation api. 7. checkedAddressBean: Address object obtained after processing with geocoder geolocation api. Optional. Structure with following fields: 1. street: String. Optional. Street line in the way it is read from address string. 2. colony: String. Optional. Colony line the way it is read from address string. (Not applicable for all countries) 3. postalCode: String. Optional. Postal code in the way it is read from address string. 4. city: String. Optional. City in the way it is read from address string. 5. state: String. Optional. State in the way it is read from address string. 6. label: String. Optional. Full address label. 8. exteriorNumber: String. Optional. Exterior street number. 9. interiorNumber: String. Optional. Interior street number. 10. addressFromStatement: String. Optional. Address as read from address statement. Lines are separated by \\n. 11. addressFieldsFromStatement: Structure with following fields: 1. street: String. Optional. Street line in the way it is read from address string. 2. colony: String. Optional. Colony line the way it is read from address string. (Not applicable for all countries) 3. postalCode: String. Optional. Postal code in the way it is read from address string. 4. city: String. Optional. City in the way it is read from address string. 5. state: String. Optional. State in the way it is read from address string. 12. invalidAddressFromStatement : Boolean. This field cheks for a valid street, numeric postal code with 5 digits, and tha both colony and city have values. (Only checked for Mexican POA) 13. addressStatementEmissionDate: Long. Optional. Issue date of address statement. The value is presented in UTC milliseconds. 14. documentType: String. Optional. Type of address statement document. Possible values: 1. Mexico: liverpool, citibanamex, cfe, telcel, izzi, axtel, telmex, oapas, sacmex, opdm, naturgy, drenaje, totalplay, dhc, att, cea, smapa, megacable, jmas, amicsa, caev 2. Bolivia: cre 3. Uruguay: ute 4. Unknown document: otherPoa 15. addressStatementTimestamps: Array. Optional. List of elements: 1. dateType: String. Description of timestamp. 2. addressStatementTimestamp: Long. UTC timestamp. 16. poaName: String. Optional. Extracted name from address statement. 17. typeOfId: String. Image was classified as one of the following: Unknown, Passport, Visa, DriversLicense, IdentificationCard, Permit, Currency, ResidenceDocument, TravelDocument, BirthCertificate, VehicleRegistration, Other, WeaponLicense, TribalIdentification, VoterIdentification, Military, TaxIdentification, FederalID, MedicalCard 18. documentFrontSubtype: String. Optional. Additional info about ID type (front side) 19. documentBackSubtype: String. Optional. Additional info about ID type (back side) 20. birthDate: Long. Optional. Date of birth is presented in UTC milliseconds. 21. gender: String. Optional. 1 character. Gender values are presented in English. "M" for male and "F" for female. 22. claveDeElector: String. Optional. 18 characters. Clave de elector as read from id. For Mexican IDs only. 23. curp: String. Optional. 18 characters. Curp as read form id. For Mexican IDs only. 24. numeroEmisionCredencial: String. Optional. 2 characters. Numero Emision Credencial as read from id. (For Mexican IDs only). 25. cic : String. Optional. 9 characters. Cic as read from id. (This field is read from back side of id; For Mexican IDs only). 26. ocr : String. Optional. 13 characters. Ocr as read from id. (This field is read from back side of id; For Mexican IDs only). 27. documentNumber: String. Optional. Document number. 28. personalNumber: String. Optional. Personal number. 29. refNumber : String. Optional. Document Reference Number. 30. taxIdNumber : String. Optional. Personal tax identification number. 31. nue: String. Optional. NUE number as read from id. (for Resident Cards) 32. externalId: String. Optional. External user id. 33. issuedAt: String. Optional. Date of issue UTC timestamp. 34. expireAt: String. Optional. Expiration date UTC timestamp. 35. issueDate: Integer. Optional. Issue year of id. 36. expirationDate: Integer. Optional. Expiration year of id. 37. registrationDate : Integer. Optional. Registration date read from id. 38. issuingCountry: String. Optional. Issuing country of document. 39. issuingState: String. Optional. Issuing state of document. 40. birthPlace : String. Optional. Birth place as read from id. 41. issuingAuthority : String. Optional. Issuing Authority as read from id. 42. height : String. Optional. Person's height as read from id. 43. weight : String. Optional. Person's weight. 44. eyeColor : String. Optional. Person's eye color. 45. hairColor : String. Optional. Person's hair color. 46. bloodType : String. Optional. Person's blood type. 47. maritalStatus : String. Optional. Person's merital status. 48. nationality : String. Optional. Person's nationality. 49. nationalityMrz : String. Optional. Person's nationality as it appears in MRZ (if present). 50. nationalityAlpha3 : String. Optional. Person's nationality Alpha3 code format. Only for Brazilian IDs. 51. race : String. Optional. Person's race. 52. dlClassDetails: Array. Optional. List of driver's license details elements: 1. dlClass: String. Driver's license class. 2. validFromDate: Long. DL class valid from UTC timestamp. 3. validToDate: Long. DL class valid to UTC timestamp. 4. additionalCodes: String. Additional codes associated with DL class. 53. governmentComparisonResults : Government validation data. Optional. Returned only for supported government validation countries. Structure with following fields: 1. paternalLastNameValid : Boolean. Indicates validity of person's paternal last name through government validation apis. 2. maternalLastNameValid : Boolean. Indicates validity of person's maternal last name through government validation apis. 3. firstNameValid : Boolean. Indicates validity of person's first name through government validation apis. 4. curpValid : Boolean. Indicates CURP validity through government validation apis. 5. ocrValid : Boolean. Indicates ocr validity through government validation apis. 6. claveDeElectorValid : Boolean. Indicates clave de elector validity through government validation apis. 7. numeroEmisionCredencialValid : Boolean. Indicates numero emision credencial validity through government validation apis. 8. registrationDateValid : Boolean. Indicates registration date validity through government validation apis. 9. issueDateValid : Boolean. Indicates issue date validity through government validation apis. 10. notExtracted : Integer. Number of not extracted OCR fields. Only for Mexican IDs. 54. notExtractedDetails : String array. List of ocr field names that were not extracted. Only for Mexican IDs. 55. classes : String. Optional. Person's driver licence classes. 56. cond : String. Optional. Person's driver licence conditions. 57. mentions : String. Optional. Person's driver licence mentions. 58. restrictions : String. Optional. Person's driver licence restrictions. 59. mrz1 : String. Optional. First MRZ line. 60. mrz2 : String. Optional. Second MRZ line. 61. mrz3 : String. Optional. Third MRZ line. 62. fullNameMrz : String. Optional. Person's full name read from MRZ. 63. documentNumberCheckDigit : String. Optional. Document number check digit read from MRZ. 64. dateOfBirthCheckDigit : String. Optional. Date of birth check digit read from MRZ. 65. expirationDateCheckDigit : String. Optional. Expiration date check digit read from MRZ. 66. barcodeRawData : String. Optional. Full unformatted data read from 2D barcode. 67. fathersName : String. Optional. Person's father's name. Only for Brazilian and Indian IDs. 68. mothersName : String. Optional. Person's mother's name. Only for Brazilian IDs. 69. federalRevenueNumber : String. Optional. Federal revenue number. Only for Brazilian IDs. 70. originDocumentId : String. Optional. Origin document ID. Only for Brazilian IDs. 71. driversLicenseCategory : String. Optional. Driver's licence category. Only for Brazilian IDs. 72. controlNumber : String. Optional. Control number. Only for Brazilian IDs. 73. renach : String. Renach. Optional. Only for Brazilian IDs. 74. ocrDataConfidence : Structure containing ocr reliability confidence for each extracted ocr field. Confidence values are Floats between 0 and 1. All fields are optional. 1. birthDateConfidence : Float. Confidence between 0 and 1. 2. nameConfidence : Float. Confidence between 0 and 1. 3. givenNameConfidence : Float. Confidence between 0 and 1. 4. firstNameConfidence : Float. Confidence between 0 and 1. 5. middleNameConfidence : Float. Confidence between 0 and 1. 6. nameSuffixConfidence : Float. Confidence between 0 and 1. 7. mothersSurnameConfidence : Float. Confidence between 0 and 1. 8. fathersSurnameConfidence : Float. Confidence between 0 and 1. 9. fullNameMrzConfidence : Float. Confidence between 0 and 1. 10. addressConfidence : Float. Confidence between 0 and 1. 11. streetConfidence : Float. Confidence between 0 and 1. 12. colonyConfidence : Float. Confidence between 0 and 1. 13. postalCodeConfidence : Float. Confidence between 0 and 1. 14. cityConfidence : Float. Confidence between 0 and 1. 15. stateConfidence : Float. Confidence between 0 and 1. 16. ...and other described ocr fields, followed by confidence suffix (ocrFieldNameConfidence) */}