Skip to main content
POST
/
v2
/
individuals
/
{entityId}
/
actions
/
idv
/
ocr
Submit an identity document photo for ocr processing. Results will be in the form of an identity document with populated with ocr results.
curl --request POST \
  --url https://api.uat.frankie.one/v2/individuals/{entityId}/actions/idv/ocr \
  --header 'Content-Type: application/json' \
  --header 'X-Frankie-CustomerID: <x-frankie-customerid>' \
  --header 'api_key: <api-key>' \
  --data '
{
  "digital": true,
  "documentId": "<string>",
  "token": "41cf9401f0f889616bef",
  "vendorParameters": {}
}
'
{
  "status": "COMPLETE_OCR",
  "individual": {
    "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdAt": "2023-11-07T05:31:56Z",
    "schemaVersion": 2,
    "addresses": [
      {
        "country": "<string>",
        "addressId": "<string>",
        "updatedAt": "2023-11-07T05:31:56Z",
        "sourceId": "<string>",
        "type": "OTHER",
        "typeDescription": "<string>",
        "validFrom": {
          "year": "1990",
          "month": "03",
          "day": "27",
          "unstructured": "12 Rajab 1445 AH",
          "type": "GREGORIAN",
          "normalized": "1990-03-31"
        },
        "validTo": {
          "year": "1990",
          "month": "03",
          "day": "27",
          "unstructured": "12 Rajab 1445 AH",
          "type": "GREGORIAN",
          "normalized": "1990-03-31"
        },
        "longForm": "<string>",
        "unitNumber": "<string>",
        "buildingName": "<string>",
        "streetName": "<string>",
        "streetNumber": "<string>",
        "streetType": "<string>",
        "neighborhood": "<string>",
        "locality": "<string>",
        "district": "<string>",
        "subdivision": "<string>",
        "postalCode": "<string>",
        "careOf": "<string>",
        "status": "CURRENT",
        "unstructuredLongForm": "<string>"
      }
    ],
    "phoneNumbers": [
      {
        "phoneNumberId": "ad165f64-5717-4562-b3fc-2c963f66bfa9",
        "isPreferred": true,
        "type": "MOBILE",
        "sourceId": "14fd5f64-5717-4562-b3fc-2c963f66ba34",
        "country": "AUS",
        "number": "0426192340",
        "linkedAddresses": [
          {
            "addressId": "fa335f64-5717-4562-b3fc-2c963f66cf41"
          }
        ],
        "unstructuredLongForm": "<string>",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "emailAddresses": [
      {
        "emailAddressId": "aa385f64-5717-4562-b3fc-2c963f66af21",
        "type": "WORK",
        "sourceId": "31dd15f64-5717-4562-b3fc-2c963f66234d",
        "email": "leonardo_dc@outlook.com",
        "isPreferred": true,
        "linkedAddresses": [
          {
            "addressId": "adc215f64-5717-4562-b3fc-2c963f66222a"
          }
        ],
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "customAttributes": {},
    "externalReferences": [
      {
        "name": "CUSTOMER-REFERENCE",
        "value": "CUST-00001342",
        "referenceId": "24de15f64-5717-4562-b3fc-2c963f66e23e",
        "type": "CUSTOMER",
        "sourceId": "93da15f64-5717-4562-b3fc-2c963f6663fe",
        "metadata": {},
        "updatedAt": "2023-11-07T05:31:56Z",
        "description": "This is the customer ID in the core banking system."
      }
    ],
    "documents": {
      "REPORT": [
        {
          "country": "AUS",
          "class": "IDENTITY",
          "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
          "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "expiryDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "issueDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "primaryIdentifier": "000734130",
          "secondaryIdentifier": "P0001975",
          "subtype": "Photo Comparison",
          "subdivision": "VIC",
          "createdAt": "2024-01-15T02:18:11.365Z",
          "updatedAt": "2025-01-16T02:18:11.365Z",
          "validFrom": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "validTo": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "sourceId": "324f15f64-5717-4562-b3fc-2c963f66ffa1",
          "supplementaryData": {
            "reference": "1",
            "nameOnCardLine1": "<string>",
            "nameOnCardLine2": "<string>",
            "nameOnCardLine3": "<string>",
            "nameOnCardLine4": "<string>",
            "middleNameOnCard": "<string>"
          },
          "customAttributes": {},
          "attachments": [
            {
              "data": {
                "uri": "https://s3.amazonaws.com/dev/41963bc5feff322020137de233c3be0fac6/croppedFrontID/38d54232-b840-431d-b248-152345fe214.jpg"
              },
              "attachmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "sourceId": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z",
              "filename": "<string>",
              "mimeType": "<string>",
              "pageNumber": 123,
              "type": "<string>",
              "location": "<string>",
              "lastMalwareScanAt": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "SUPPORTING": [
        {
          "country": "AUS",
          "class": "IDENTITY",
          "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
          "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "expiryDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "issueDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "primaryIdentifier": "000734130",
          "secondaryIdentifier": "P0001975",
          "subtype": "Photo Comparison",
          "subdivision": "VIC",
          "createdAt": "2024-01-15T02:18:11.365Z",
          "updatedAt": "2025-01-16T02:18:11.365Z",
          "validFrom": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "validTo": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "sourceId": "324f15f64-5717-4562-b3fc-2c963f66ffa1",
          "supplementaryData": {
            "reference": "1",
            "nameOnCardLine1": "<string>",
            "nameOnCardLine2": "<string>",
            "nameOnCardLine3": "<string>",
            "nameOnCardLine4": "<string>",
            "middleNameOnCard": "<string>"
          },
          "customAttributes": {},
          "attachments": [
            {
              "data": {
                "uri": "https://s3.amazonaws.com/dev/41963bc5feff322020137de233c3be0fac6/croppedFrontID/38d54232-b840-431d-b248-152345fe214.jpg"
              },
              "attachmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "sourceId": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z",
              "filename": "<string>",
              "mimeType": "<string>",
              "pageNumber": 123,
              "type": "<string>",
              "location": "<string>",
              "lastMalwareScanAt": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "IDENTITY": [
        {
          "country": "AUS",
          "class": "IDENTITY",
          "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
          "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "expiryDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "issueDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "primaryIdentifier": "000734130",
          "secondaryIdentifier": "P0001975",
          "subtype": "Photo Comparison",
          "subdivision": "VIC",
          "createdAt": "2024-01-15T02:18:11.365Z",
          "updatedAt": "2025-01-16T02:18:11.365Z",
          "validFrom": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "validTo": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "sourceId": "324f15f64-5717-4562-b3fc-2c963f66ffa1",
          "supplementaryData": {
            "reference": "1",
            "nameOnCardLine1": "<string>",
            "nameOnCardLine2": "<string>",
            "nameOnCardLine3": "<string>",
            "nameOnCardLine4": "<string>",
            "middleNameOnCard": "<string>"
          },
          "customAttributes": {},
          "attachments": [
            {
              "data": {
                "uri": "https://s3.amazonaws.com/dev/41963bc5feff322020137de233c3be0fac6/croppedFrontID/38d54232-b840-431d-b248-152345fe214.jpg"
              },
              "attachmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "sourceId": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z",
              "filename": "<string>",
              "mimeType": "<string>",
              "pageNumber": 123,
              "type": "<string>",
              "location": "<string>",
              "lastMalwareScanAt": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ],
      "OTHER": [
        {
          "country": "AUS",
          "class": "IDENTITY",
          "documentId": "92de15f64-5717-4562-b3fc-2c963f6665a7",
          "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "expiryDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "issueDate": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "primaryIdentifier": "000734130",
          "secondaryIdentifier": "P0001975",
          "subtype": "Photo Comparison",
          "subdivision": "VIC",
          "createdAt": "2024-01-15T02:18:11.365Z",
          "updatedAt": "2025-01-16T02:18:11.365Z",
          "validFrom": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "validTo": {
            "year": "1990",
            "month": "03",
            "day": "27",
            "unstructured": "12 Rajab 1445 AH",
            "type": "GREGORIAN",
            "normalized": "1990-03-31"
          },
          "sourceId": "324f15f64-5717-4562-b3fc-2c963f66ffa1",
          "supplementaryData": {
            "reference": "1",
            "nameOnCardLine1": "<string>",
            "nameOnCardLine2": "<string>",
            "nameOnCardLine3": "<string>",
            "nameOnCardLine4": "<string>",
            "middleNameOnCard": "<string>"
          },
          "customAttributes": {},
          "attachments": [
            {
              "data": {
                "uri": "https://s3.amazonaws.com/dev/41963bc5feff322020137de233c3be0fac6/croppedFrontID/38d54232-b840-431d-b248-152345fe214.jpg"
              },
              "attachmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "sourceId": "<string>",
              "createdAt": "2023-11-07T05:31:56Z",
              "updatedAt": "2023-11-07T05:31:56Z",
              "filename": "<string>",
              "mimeType": "<string>",
              "pageNumber": 123,
              "type": "<string>",
              "location": "<string>",
              "lastMalwareScanAt": "2023-11-07T05:31:56Z"
            }
          ]
        }
      ]
    },
    "sourceId": "<string>",
    "name": {
      "familyName": "Doe",
      "nameId": "87654321-4321-4321-4321-210987654321",
      "language": "eng",
      "givenName": "John",
      "middleName": "R",
      "otherName": null,
      "prefix": "Dr.",
      "suffix": "Jr.",
      "sourceId": "87654321-4321-4321-4321-210987654322",
      "displayName": "John Doe",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "alternateNames": [
      {
        "familyName": "Doe",
        "nameId": "87654321-4321-4321-4321-210987654321",
        "language": "eng",
        "givenName": "John",
        "middleName": "R",
        "otherName": null,
        "prefix": "Dr.",
        "suffix": "Jr.",
        "sourceId": "87654321-4321-4321-4321-210987654322",
        "displayName": "John Doe",
        "type": "OTHER",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "dateOfBirth": {
      "dateOfBirthId": "<string>",
      "sourceId": "<string>",
      "updatedAt": "2023-11-07T05:31:56Z",
      "year": "1990",
      "month": "03",
      "day": "27",
      "unstructured": "12 Rajab 1445 AH",
      "type": "GREGORIAN",
      "normalized": "1990-03-31"
    },
    "alternateDatesOfBirth": [
      {
        "dateOfBirthId": "<string>",
        "sourceId": "<string>",
        "updatedAt": "2023-11-07T05:31:56Z",
        "year": "1990",
        "month": "03",
        "day": "27",
        "unstructured": "12 Rajab 1445 AH",
        "type": "GREGORIAN",
        "normalized": "1990-03-31"
      }
    ],
    "gender": {
      "genderId": "<string>",
      "sourceId": "<string>"
    },
    "placeOfBirth": {
      "country": "USA",
      "addressId": "6ad15f64-5717-4562-b3fc-2c963f66abf9",
      "sourceId": "1da65f64-5717-4562-b3fc-2c963f669fba",
      "longForm": "525 Kent Dr, Harlem NY 10037, USA",
      "unstructuredLongForm": "3A/525 KENT DRIVE HARLEM NEW YORK 10036 USA",
      "unitNumber": "3A",
      "buildingName": "EQ Tower",
      "streetName": "Kent",
      "streetNumber": "525",
      "streetType": "Dr",
      "neighborhood": "Harlem",
      "locality": "Manhattan",
      "district": "New York County",
      "subdivision": "NY",
      "postalCode": "10037"
    },
    "nationality": "AUS",
    "consents": [
      {
        "type": "UNDER18",
        "schemaVersion": 123,
        "sourceId": "93da15f64-5717-4562-b3fc-2c963f6663fe"
      }
    ],
    "informationSources": {},
    "relationships": {
      "duplicates": [
        {
          "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "origin": {
            "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "processResultId": "<string>",
            "createdAt": "2023-11-07T05:31:56Z"
          }
        }
      ]
    }
  },
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
  "ocrResult": {
    "processResultId": "<string>",
    "schemaVersion": 123,
    "entityId": "<string>",
    "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
    "stepName": "<string>",
    "stepType": "<string>",
    "objectType": "<string>",
    "objectId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "groupId": "<string>",
    "providerResult": {
      "name": "<string>",
      "source": "<string>",
      "sourceNormalized": "<string>",
      "reference": "<string>",
      "fuzziness": {
        "normalized": 50,
        "actual": "<string>"
      },
      "confidence": {
        "normalized": 50,
        "actual": "<string>"
      },
      "riskScore": 123,
      "errorCode": "<string>",
      "errorMessage": "<string>"
    },
    "subClass": "<string>",
    "supplementaryData": {
      "serviceProvider": "<string>",
      "searchId": "<string>",
      "caseId": "<string>",
      "referenceId": "<string>",
      "originalStepSearchLevel": "<string>",
      "groupingId": "<string>",
      "reportUrl": "<string>",
      "fuzziness": {
        "normalized": 50,
        "actual": "<string>"
      },
      "matchData": {
        "spReferenceId": "<string>",
        "name": "<string>",
        "strength": 123,
        "givenName": "<string>",
        "otherName": "<string>",
        "familyName": "<string>",
        "date": "<string>",
        "address": "<string>",
        "countries": [
          {
            "code": "<string>",
            "matchType": "<string>"
          }
        ],
        "nationalId": {
          "idNumber": "<string>",
          "idType": "<string>",
          "idExpiry": "<string>",
          "issuingCountryCode": "<string>",
          "documentId": "<string>"
        },
        "imageUrl": "<string>",
        "isDeceased": true,
        "isAlias": true,
        "isRelated": true
      },
      "aliases": [
        "<string>"
      ],
      "relatedParties": [
        {
          "name": "<string>",
          "relationship": "<string>"
        }
      ],
      "referenceDocs": [
        {
          "url": "<string>",
          "description": "<string>"
        }
      ],
      "notes": {},
      "pepData": [
        {
          "countryCode": "<string>",
          "countryName": "<string>",
          "sourceName": "<string>",
          "level": "<string>",
          "sourceUrl": "<string>",
          "sourcePosition": "<string>",
          "position": "<string>",
          "positionDescription": "<string>",
          "status": "<string>",
          "listingStart": "<string>",
          "listingEnd": "<string>",
          "imageUrl": "<string>",
          "referenceDocs": [
            {
              "url": "<string>",
              "description": "<string>"
            }
          ],
          "additionalData": [
            {
              "key": "<string>",
              "value": "<string>"
            }
          ]
        }
      ],
      "sanctionData": [
        {
          "countryCode": "<string>",
          "countryName": "<string>",
          "sourceName": "<string>",
          "sourceUrl": "<string>",
          "sourceReason": "<string>",
          "listingStart": "<string>",
          "listingEnd": "<string>",
          "imageUrl": "<string>",
          "referenceDocs": [
            {
              "url": "<string>",
              "description": "<string>"
            }
          ],
          "additionalData": [
            {
              "key": "<string>",
              "value": "<string>"
            }
          ]
        }
      ],
      "watchlistData": [
        {
          "countryCode": "<string>",
          "countryName": "<string>",
          "sourceName": "<string>",
          "sourceUrl": "<string>",
          "sourceReason": "<string>",
          "listingStart": "<string>",
          "listingEnd": "<string>",
          "imageUrl": "<string>",
          "referenceDocs": [
            {
              "url": "<string>",
              "description": "<string>"
            }
          ],
          "additionalData": [
            {
              "key": "<string>",
              "value": "<string>"
            }
          ]
        }
      ],
      "mediaData": [
        {
          "title": "<string>",
          "source": "<string>",
          "snippet": "<string>",
          "sourceDate": "<string>",
          "sourceCountry": "<string>",
          "url": "<string>",
          "isCurrent": true
        }
      ]
    },
    "errors": [
      {
        "code": "<string>",
        "description": "<string>",
        "location": "<string>"
      }
    ],
    "notes": {},
    "systemStatus": "VALID",
    "riskFactors": [
      {
        "factor": "<string>",
        "value": "<string>"
      }
    ],
    "updatedBy": "<string>"
  }
}

Authorizations

​
api_key
string
header
required

Headers

​
api_key
string
required

Your API key provided by FrankieOne

Example:

"245c765b124a098d09ef8765...."

​
X-Frankie-CustomerID
string
required

Your Customer ID provided by FrankieOne

Example:

"12345678-1234-1234-1234-123456789012"

​
X-Frankie-CustomerChildID
string

Your Customer Child ID provided by FrankieOne

Example:

"87654321-4321-4321-4321-210987654321"

​
X-Frankie-Channel
string

Open string that can be used to define the "channel" the request comes in from. It can potentially be used in routing and risk calculations upon request. Default values that can be used are: api portal smartui Any alphanumeric string is supported though. Anything over 64 characters will be truncated.

Path Parameters

​
entityId
string
required

Unique FrankieOne identifier for an entity

Body

application/json

OCR request, used to submit an image of an identity document for OCR processing. The image can be uploaded via a vendor SDK after calling get IDV token, or can be submitted directly as a fileData.

​
digital
boolean

Is this a digital version of the id, eg Digital Driver Licence screenshot. If not provided assumed to be false.

​
documentId
string

document id if known that the scan data should be attached to

​
fileData
object

Document attachment details.

​
token
string

if the image was captured via a provder SDK, pass through the token instead of the fileData

Example:

"41cf9401f0f889616bef"

​
vendorParameters
object

Vendor-specific parameters

Response

OK

OCR response

​
status
enum<string>

Status of the OCR process. Status can be one of:

  • AWAITING_OCR_RESULTS_PROVIDER_OFFLINE - the provider is offline and the OCR results are not available
  • AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE - the document type is not supported, mostly only passport, driving license and national id are supported but this is provider specific
  • WAITING_DOCUMENT_UPLOAD_FAILED_OCR - the document upload failed to the provider
  • AWAITING_DOCUMENT_OCR - the document is being processed by the provider still and it awaiting results
  • DOCUMENT_INVALID_EXCEEDED_SIZE_LIMIT - the document is too large to be processed
  • DOCUMENT_INVALID_INCORRECT_FILE_FORMAT - the document is not a supported file format, mostly only jpeg and png are supported but this is provider specific
  • AWAITING_DOCUMENT_UPLOAD_BACK - the back of the document needs to be uploaded
  • AWAITING_DOCUMENT_UPLOAD_FRONT - the front of the document needs to be upload
  • COMPLETE_OCR - document OCR is valid and completed
Available options:
AWAITING_OCR_RESULTS_PROVIDER_OFFLINE,
AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE,
WAITING_DOCUMENT_UPLOAD_FAILED_OCR,
AWAITING_DOCUMENT_OCR,
DOCUMENT_INVALID_EXCEEDED_SIZE_LIMIT,
DOCUMENT_INVALID_INCORRECT_FILE_FORMAT,
AWAITING_DOCUMENT_UPLOAD_BACK,
AWAITING_DOCUMENT_UPLOAD_FRONT,
COMPLETE_OCR
Example:

"COMPLETE_OCR"

​
individual
object
​
requestId
string

The unique request identifier for the API call made.

Example:

"01HN9XHZN6MGXM9JXG50K59Q85"

​
ocrResult
object