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

StatusDescription
DOCUMENT_INVALID_INCORRECT_FILE_FORMATThe file format is not accepted by the third-party OCR provider
DOCUMENT_INVALID_EXCEEDED_SIZE_LIMITFile size exceeds the limits supported by third-party OCR provider
COMPLETE_OCRThe OCR process was successful and is complete now.
AWAITING_OCR_RESULTS_PROVIDER_OFFLINEThe result cannot be retrieved from the provider due to an issue.
AWAITING_DOCUMENT_UPLOAD_INVALID_TYPEThe document is invalid.
AWAITING_DOCUMENT_UPLOAD_FRONTThe front side of the image is required to complete the OCR.
AWAITING_DOCUMENT_UPLOAD_FAILED_OCRThe capture successful, but an error happened during upload, potentially due to a bad scan
AWAITING_DOCUMENT_UPLOAD_BACKThe 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"
}