OCR extraction API
The OCR extraction API performs OCR on an ID document and returns the data extracted from the provided image.
To extract the OCR result of an ID image, you need to have an entity created in Frankie via Create New Entity. You must capture consent from the user when gathering information. The user consent can be added by a normal entity update, passing through the consent.general flag, or at the time of entity creation. For more info on consent, refer to About consent.
You also need to provide a base64 encoded blob of the ID image. The API accepts only one image at a time, so you can only provide either the ID document's front or back image. The API returns the results synchronously, along with a status in the response which determines whether the result is complete or requires a second image.
The Frankie service creates a document object with the OCR result and attaches it to the entity. The updated entity will be then returned in the response.
The valid document types are Australian DL, and Passport (any country), so if the document type is anything else, the service will return a failure.
OCR capture via OneSDK
You can also simply use OneSDK in your application to capture document details via OCR. The SDK connects to this API to perform OCR.
Understanding the results
Statuses
| Status | Description |
|---|---|
| DOCUMENT_INVALID_INCORRECT_FILE_FORMAT | The file format is not accepted by the third-party OCR provider |
| DOCUMENT_INVALID_EXCEEDED_SIZE_LIMIT | File size exceeds the limits supported by third-party OCR provider |
| COMPLETE_OCR | The OCR process was successful and is complete now. |
| AWAITING_OCR_RESULTS_PROVIDER_OFFLINE | The result cannot be retrieved from the provider due to an issue. |
| AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE | The document is invalid. |
| AWAITING_DOCUMENT_UPLOAD_FRONT | The front side of the image is required to complete the OCR. |
| AWAITING_DOCUMENT_UPLOAD_FAILED_OCR | The capture successful, but an error happened during upload, potentially due to a bad scan |
| AWAITING_DOCUMENT_UPLOAD_BACK | The back side of the image is required to complete the OCR. |
OCR comparison
When Frankie's service processes the OCR results, it compares the extracted info with the entity info which was gathered from the user. If there are any mismatches, the service will report them under ocr_scanned_mismatch KVP in the response.
The following fields are considered for the OCR comparison:
- First name
- Last name
- DOB
- ID document number
- State of the ID document (Optional, can be configured)
- ID card number (Optional, can be configured)
Example
Sample request:
curl --request POST \
--url https://api.kycaml.uat.frankiefinancial.io/idv/v2/idvalidate/ocr \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"entity": {
"entityId": "09dc9c8a-0a83-4669-20cc-e3a108b4c54c"
},
"fileData": {
"scanFilename": "DL.jpeg",
"scanMIME": "image/jpeg",
"scanSide": "F",
"scanType": "PHOTO",
"scanData": "VGhpcyBpcyBzb21lIGV4YW1wbGUgZGF0YS4gV29vLCBJIGJldCB5b3UgcmVncmV0IHRoZSB0aW1lIHlvdSB3YXN0ZWQgZGVjb2RpbmcgdGhpcywgaHVoPw=="
}
}
'
Sample response:
{
"entity": {
"addresses": [
{
"addressId": "54bd0de9-547f-75e9-f0fd-018e7a264121",
"addressType": "RESIDENTIAL1",
"country": "AUS",
"endDate": "0001-01-01",
"longForm": "59 Carlton Street, Carlton Victoria 3053, Australia",
"postalCode": "3053",
"startDate": "0001-01-01",
"state": "VIC",
"streetName": "Carlton Street",
"streetNumber": "59",
"town": "Carlton"
}
],
"dateOfBirth": {
"dateOfBirth": "2000-01-01",
"yearOfBirth": "2000"
},
"entityId": "09dc9c8a-0a83-4669-20cc-e3a108b4c54c",
"entityProfile": "safe_harbour_id",
"entityType": "INDIVIDUAL",
"extraData": [
{
"kvpKey": "kyc.method",
"kvpValue": "electronic"
},
{
"kvpKey": "customer_reference",
"kvpType": "id.external"
},
{
"kvpKey": "consent.general",
"kvpValue": "true"
},
{
"kvpKey": "consent.docs",
"kvpValue": "true"
}
],
"identityDocs": [
{
"country": "AUS",
"createdFromScan": true,
"docScan": [
{
"scanCreated": "0001-01-01T00:00:00.000Z",
"scanDataRetrievalState": "EXCLUDED",
"scanDocId": "6086133f-be9d-31b3-f15e-570f0f47cafd",
"scanFilename": "DL.jpeg",
"scanMIME": "image/jpeg",
"scanSide": "F",
"scanType": "PHOTO"
}
],
"documentId": "907bcba7-18ad-e9c8-bb66-351e645dbfd3",
"extraData": [
{
"kvpKey": "ocrApplicantId",
"kvpType": "general.string",
"kvpValue": "01GF4J7F43R817NNVQMWFXTN6C"
},
{
"kvpKey": "ocr_process_status",
"kvpType": "general.string",
"kvpValue": "COMPLETE_OCR"
},
{
"kvpKey": "ocr_scanned_date_of_expiry",
"kvpType": "general.string",
"kvpValue": "01/01/2031"
},
{
"kvpKey": "ocr_accuracy_date_of_expiry",
"kvpType": "general.float",
"kvpValue": "98.000000"
},
{
"kvpKey": "ocr_scanned_document_number",
"kvpType": "general.string",
"kvpValue": "036719436"
},
{
"kvpKey": "ocr_accuracy_document_number",
"kvpType": "general.float",
"kvpValue": "99.000000"
},
{
"kvpKey": "ocr_scanned_date_of_birth",
"kvpType": "general.string",
"kvpValue": "01-01-2000"
},
{
"kvpKey": "ocr_accuracy_date_of_birth",
"kvpType": "general.float",
"kvpValue": "96.000000"
},
{
"kvpKey": "ocr_scanned_last_name",
"kvpType": "general.string",
"kvpValue": "TEST"
},
{
"kvpKey": "ocr_accuracy_last_name",
"kvpType": "general.float",
"kvpValue": "98.000000"
},
{
"kvpKey": "ocr_scanned_issuing_country",
"kvpType": "general.string",
"kvpValue": "Australia"
},
{
"kvpKey": "ocr_accuracy_issuing_country",
"kvpType": "general.float",
"kvpValue": "98.900002"
},
{
"kvpKey": "ocr_scanned_first_name",
"kvpType": "general.string",
"kvpValue": "TEST"
},
{
"kvpKey": "ocr_accuracy_first_name",
"kvpType": "general.float",
"kvpValue": "100.000000"
},
{
"kvpKey": "ocr_scanned_middle_name",
"kvpType": "general.string",
"kvpValue": "TEST"
},
{
"kvpKey": "ocr_accuracy_middle_name",
"kvpType": "general.float",
"kvpValue": "100.000000"
},
{
"kvpKey": "ocr_scanned_document_type",
"kvpType": "general.string",
"kvpValue": "Driver Licence"
},
{
"kvpKey": "ocr_accuracy_document_type",
"kvpType": "general.float",
"kvpValue": "98.998550"
},
{
"kvpKey": "ocr_scanned_issuing_state",
"kvpType": "general.string",
"kvpValue": "VIC"
},
{
"kvpKey": "ocr_accuracy_issuing_state",
"kvpType": "general.float",
"kvpValue": "100.000000"
},
{
"kvpKey": "report.dimensions",
"kvpType": "general.string",
"kvpValue": "clear"
},
{
"kvpKey": "report.glare",
"kvpType": "general.string",
"kvpValue": "clear"
},
{
"kvpKey": "report.sharpness",
"kvpType": "general.string",
"kvpValue": "clear"
},
{
"kvpKey": "report.days_to_expiration",
"kvpType": "general.string",
"kvpValue": "3323"
},
{
"kvpKey": "report.expired",
"kvpType": "general.string",
"kvpValue": "No"
},
{
"kvpKey": "report.over18",
"kvpType": "general.string",
"kvpValue": "clear"
},
{
"kvpKey": "report.over21",
"kvpType": "general.string",
"kvpValue": "clear"
},
{
"kvpKey": "report.nfc_supported",
"kvpType": "general.string",
"kvpValue": "FALSE"
},
{
"kvpKey": "id_ocr_scan_result",
"kvpType": "general.string",
"kvpValue": "CLEAR"
},
{
"kvpKey": "ocr_scanned_mismatch",
"kvpType": "general.string",
"kvpValue": "ocr_scanned_last_name,ocr_scanned_document_number,ocr_scanned_date_of_birth"
},
{
"kvpKey": "id_provider_id",
"kvpType": "general.string"
},
{
"kvpKey": "idv_check_id",
"kvpType": "general.string",
"kvpValue": "01GF4J7F43R817NNVQMWFXTN6C"
},
{
"kvpKey": "idv_reports_count",
"kvpType": "general.integer",
"kvpValue": "1"
},
{
"kvpKey": "idv_webcapture_check_id",
"kvpType": "general.string",
"kvpValue": "01GFMBSFKZMRW4HZDWVTA8R87H"
},
{
"kvpKey": "id_create_date",
"kvpType": "general.datetime",
"kvpValue": "2022-10-18T01:37:18Z"
},
{
"kvpKey": "ocr_process_run_date",
"kvpType": "general.datetime",
"kvpValue": "2022-10-18T01:37:19Z"
}
],
"idExpiry": "2026-08-08",
"idIssued": "0001-01-01",
"idNumber": "8163546",
"idType": "DRIVERS_LICENCE",
"region": "VIC"
}
],
"name": {
"familyName": "Test",
"givenName": "Ramin"
}
},
"status": "COMPLETE_OCR"
}
Updated 5 months ago