OCR Extraction Document API — FrankieOne

When onboarding users, businesses need to verify identity documents (ID) and extract information accurately. This API provides OCR (Optical Character Recognition) capabilities to extract information from identity documents, specifically Australian Driver’s Licenses and Passports from any country.

Document Requirements

Different identity documents have different image requirements:

Australian Driver’s License

Requires both front and back images
Must submit front image first, then back image
Both images are mandatory for complete processing

Passport (Any Country)

Requires only the main identity page
Single image submission is sufficient
Status will be COMPLETE_OCR after successful processing

Implementation Guide

Step 1: Create Entity

First, create an entity to store the OCR results

POST https://api.kycaml.uat.frankiefinancial.io/compliance/v1.2/entity
Body Content:
{
	"entityProfile": "gov_id",
	"entityType": "INDIVIDUAL",
	"name": {
		"givenName": "testingAccount"
	},
	"extraData": [
		{
			"kvpKey": "customer_reference",
			"kvpType": "id.external",
			"kvpValue": "customerOnboardingPerson"
		},
		{
			"kvpKey": "consent.general",
			"kvpValue": "true"
		},
		{
			"kvpKey": "consent.docs",
			"kvpValue": "true"
		},
		{
			"kvpKey": "consent.creditheader",
			"kvpValue": "true"
		}
	]
}
RESPONSE
{
	"entity": {
		"entityId": "1b1c123b-a058-4b78-ae00-d124fabe2057",
		// ... other entity details
	}
}

Step 2: Submit First Image

Submit the first (or only) image of the document.
POST https://api.kycaml.uat.frankiefinancial.io/idv/v2/idvalidate/ocr
{
	"entity": {
		"entityId": "1b1c123b-a058-4b78-ae00-d124fabe2057"  //Entity ID from step 1
	},
	"fileData": {
		"scanFilename": "DL_front.jpeg",
		"scanMIME": "image/jpeg",
		"scanSide": "F",
		"scanType": "PHOTO",
		"scanData": "<base64-encoded-image>"
	}
}

Step 3: Check Response Status

After submitting the first image, check the response status of the data returned in step 2 to determine next steps:

{
	"entity": {
		"entityId": "1b1c123b-a058-4b78-ae00-d124fabe2057",
		"identityDocs": [
			{
				"documentId": "136a9526-3b6c-5155-b0b4-2cd40dc475ce",
				"extraData": [
					{
						"kvpKey": "ocr_process_status",
						"kvpType": "general.string",
						"kvpValue": "AWAITING_DOCUMENT_UPLOAD_BACK"
					}
				]
			}
		]
	},
	"status": "AWAITING_DOCUMENT_UPLOAD_BACK"   // <-- This is what you're looking for
}

Status Handling

If status is COMPLETE_OCR:
1. Processing is complete
2. Proceed to Step 5 (Extract Data)
If status is AWAITING_DOCUMENT_UPLOAD_BACK:
1. Document requires back image (Australian Driver’s License)
2.Store the documentId from the response Proceed to Step 4 (Submit Back Image)
If status indicates an error:
1. DOCUMENT_INVALID_INCORRECT_FILE_FORMAT: Check file format
2. DOCUMENT_INVALID_EXCEEDED_SIZE_LIMIT: ReKuyaduce image size
3. AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE: Verify document type
4. AWAITING_DOCUMENT_UPLOAD_FAILED_OCR: Improve image quality

Step 4: Submit Back Image (If Required)

Only required for Australian Driver’s License when status is AWAITING_DOCUMENT_UPLOAD_BACK.

POST https://api.kycaml.uat.frankiefinancial.io/idv/v2/idvalidate/ocr
{
	"documentId": "136a9526-3b6c-5155-b0b4-2cd40dc475ce",
	"entity": {
		"entityId": "1b1c123b-a058-4b78-ae00-d124fabe2057"
	},
	"fileData": {
		"scanFilename": "DL_back.jpeg",
		"scanMIME": "image/jpeg",
		"scanSide": "B",
		"scanType": "PHOTO",
		"scanData": "<base64-encoded-image>"
	}
}

Step 5: Extract OCR Data

Once status is COMPLETE_OCR, extract the relevant data from the response: (parts of this response has been truncated for brevity)

{
	"entity": {
	....
		"identityDocs": [
			{
				"extraData": [
					{
						"kvpKey": "ocr_scanned_first_name",
						"kvpValue": "BRUCE"
					},
					{
						"kvpKey": "ocr_scanned_middle_name",
						"kvpValue": "F"
					},
					{
						"kvpKey": "ocr_scanned_last_name",
						"kvpValue": "TESTNINE"
					},
					{
						"kvpKey": "ocr_scanned_date_of_birth",
						"kvpValue": "1958-01-01"
					},
					{
						"kvpKey": "ocr_scanned_address_long",
						"kvpValue": "81 ARGYLE ROAD MARY VIC 3465"
					}
				]
			}
		]
	}
}

Step 6: Update Entity

Using the above action will return the OCR extracted values as part of the response but will NOT update the values on the document.

Call the updateAndVerifyEntity endpoint to provide the extracted data and trigger checks, specifically:

POST https://api.kycaml.uat.frankiefinancial.io/compliance/v1.2/entity/{entityId}/verify/profile
{
    "entity": {
        "entityId": "entityId",
        "dateOfBirth": {
            "dateOfBirth": "1990-01-01" // OPTIONAL: OCR extracted DOB
        },
        "name": {
            "familyName": "Smith", // OPTIONAL: OCR extracted familyName
            "middleName":"F",
            "givenName": "Johnothan" // OPTIONAL: OCR extracted givenName
        },
        "identityDocs": [
            {
                "documentId": "documentId", // ID of document you're updating
                "extraData": [
                    {
                        "kvpKey": "document_number",
                        "kvpValue": "cardNumber" // OCR extracted cardNumber
                    }
                ],
                "country": "AUS",
                "idType": "DRIVERS_LICENCE",
                "idNumber": "idNumber", // OCR extracted idNumber
                "region": "state" // OCR extracted state
            }
        ]
    }
}

Important Notes

Document Type Detection
- The API automatically detects the document type.
- Response status will indicate if more images are needed.
- Always check the status before proceeding.
Data quality
- Check ocr_scanned_mismatch for discrepancies.
- Monitor confidence scores (for example, first_name_ocr_data_confidence).
- Higher confidence scores indicate better data quality.
Adress Handling
- ocr_scanned_address_long is only reliable for Australian documents.
- For non-Australian documents, collect address manually.
Error Handling
- Implement retry logic for provider offline errors.
- Validate image quality before submission.
- Store both entityId and documentId for error recovery.

Postman Collection

Download Postman Collection