Skip to main content
POST
/
idvalidate
/
ocr
Process an identity document photo for ocr
curl --request POST \
  --url https://api.uat.frankie.one/idv/v2/idvalidate/ocr \
  --header 'Content-Type: application/json' \
  --header 'X-Frankie-CustomerID: <x-frankie-customerid>' \
  --header 'api_key: <api-key>' \
  --data '
{
  "digital": true,
  "documentId": "<string>",
  "entity": {
    "addresses": [
      {
        "addressId": "<string>",
        "addressType": "<string>",
        "buildingName": "<string>",
        "careOf": "<string>",
        "country": "<string>",
        "endDate": "<string>",
        "extraData": [
          {
            "kvpKey": "<string>",
            "kvpType": "<string>",
            "kvpValue": "<string>"
          }
        ],
        "longForm": "<string>",
        "postalCode": "<string>",
        "region": "<string>",
        "startDate": "<string>",
        "state": "<string>",
        "streetName": "<string>",
        "streetNumber": "<string>",
        "streetType": "<string>",
        "suburb": "<string>",
        "town": "<string>",
        "unitNumber": "<string>",
        "unstructuredLongForm": "<string>"
      }
    ],
    "dateOfBirth": {
      "country": "<string>",
      "dateOfBirth": "<string>",
      "locality": "<string>",
      "unstructuredDateOfBirth": "<string>",
      "yearOfBirth": "<string>"
    },
    "entityId": "<string>",
    "entityProfile": "<string>",
    "entityType": "<string>",
    "extraData": [
      {
        "kvpKey": "<string>",
        "kvpType": "<string>",
        "kvpValue": "<string>"
      }
    ],
    "flags": [
      {
        "flag": "<string>",
        "value": 123
      }
    ],
    "gender": "<string>",
    "identityDocs": [
      {
        "country": "<string>",
        "createdFromScan": true,
        "docScan": [
          {
            "ScanDelete": true,
            "scanCreated": "<string>",
            "scanData": "<string>",
            "scanDataRetrievalState": "<string>",
            "scanDocId": "<string>",
            "scanFilename": "<string>",
            "scanMIME": "<string>",
            "scanPageNum": 123,
            "scanSide": "<string>",
            "scanType": "<string>"
          }
        ],
        "documentId": "<string>",
        "documentStatus": "<string>",
        "extraData": [
          {
            "kvpKey": "<string>",
            "kvpType": "<string>",
            "kvpValue": "<string>"
          }
        ],
        "idExpiry": "<string>",
        "idIssued": "<string>",
        "idNumber": "<string>",
        "idSubType": "<string>",
        "idType": "<string>",
        "manuallyModified": true,
        "region": "<string>"
      }
    ],
    "name": {
      "displayName": "<string>",
      "familyName": "<string>",
      "givenName": "<string>",
      "honourific": "<string>",
      "middleName": "<string>"
    },
    "organisationData": {
      "adverseCreditDataPresent": true,
      "aliases": [
        "<string>"
      ],
      "blockingReasons": [
        {
          "candidates": [
            {
              "address": "<string>",
              "code": "<string>",
              "countryIso": "<string>",
              "registeredName": "<string>",
              "registryDescription": "<string>",
              "subdivision": "<string>"
            }
          ],
          "description": "<string>",
          "type": "<string>"
        }
      ],
      "class": {
        "code": "<string>",
        "description": "<string>"
      },
      "contactDetails": {
        "email": "<string>",
        "faxNumber": "<string>",
        "telephoneNumber": "<string>",
        "websiteURL": "<string>"
      },
      "disclosingEntityIndicator": true,
      "includesNonBeneficiallyHeld": true,
      "industryCodes": [
        {
          "code": "<string>",
          "description": "<string>"
        }
      ],
      "industryDeclarations": [
        {
          "description": "<string>",
          "language": "<string>"
        }
      ],
      "kycCustomerType": "<string>",
      "lastCheckDate": "<string>",
      "legalFormDetails": {
        "basis": "<string>",
        "capital": "<string>",
        "comments": "<string>",
        "control": "<string>",
        "incorp": "<string>",
        "partner": "<string>",
        "responsibility": "<string>",
        "stocks": "<string>"
      },
      "normalisedLegalStatus": "<string>",
      "ownershipResolved": true,
      "registeredName": "<string>",
      "registration": {
        "countryIso": "<string>",
        "date": "<string>",
        "number": "<string>",
        "previousNumber": "<string>",
        "registryCode": "<string>",
        "registryDescription": "<string>",
        "state": "<string>",
        "unstructuredDate": "<string>",
        "unstructuredFoundationDate": "<string>"
      },
      "registries": {
        "abr": {
          "abn": "<string>",
          "acn": "<string>",
          "addresses": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>",
              "postcode": "<string>",
              "stateCode": "<string>"
            }
          ],
          "businessNames": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>",
              "name": "<string>",
              "type": "<string>"
            }
          ],
          "charityEndorsements": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>",
              "type": "<string>"
            }
          ],
          "charityTypes": [
            {
              "description": "<string>",
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>"
            }
          ],
          "description": "<string>",
          "dgrEndorsements": [
            {
              "endorsedFrom": "<string>",
              "endorsedTo": "<string>"
            }
          ],
          "gst": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>"
            }
          ],
          "historicalChanges": [
            {
              "businessName": [
                "<string>"
              ],
              "date": "<string>",
              "entityStatus": [
                "<string>"
              ],
              "goodsAndServicesTax": [
                "<string>"
              ],
              "mainBusinessPhysicalAddress": [
                "<string>"
              ],
              "mainName": [
                "<string>"
              ],
              "mainTradingName": [
                "<string>"
              ]
            }
          ],
          "lastUpdated": "<string>",
          "name": "<string>",
          "registeredDate": "<string>",
          "status": "<string>",
          "statusEffectiveFrom": "<string>",
          "type": "<string>",
          "typeCode": "<string>",
          "updatedDate": "<string>"
        }
      },
      "reviewDate": "<string>",
      "shareStructure": [
        {
          "amountDue": 123,
          "amountPaid": 123,
          "classCode": "<string>",
          "classTitle": "<string>",
          "docNumber": "<string>",
          "docNumberQualifier": "<string>",
          "sharesIssued": 123,
          "status": "<string>"
        }
      ],
      "startDate": "<string>",
      "status": {
        "code": "<string>",
        "description": "<string>"
      },
      "subType": {
        "code": "<string>",
        "description": "<string>"
      },
      "subclass": {
        "code": "<string>",
        "description": "<string>"
      },
      "type": {
        "code": "<string>",
        "description": "<string>"
      }
    }
  },
  "fileData": {
    "ScanDelete": true,
    "scanCreated": "<string>",
    "scanData": "<string>",
    "scanDataRetrievalState": "<string>",
    "scanDocId": "<string>",
    "scanFilename": "<string>",
    "scanMIME": "<string>",
    "scanPageNum": 123,
    "scanSide": "<string>",
    "scanType": "<string>"
  },
  "token": "<string>"
}
'
{
  "entity": {
    "addresses": [
      {
        "addressId": "<string>",
        "addressType": "<string>",
        "buildingName": "<string>",
        "careOf": "<string>",
        "country": "<string>",
        "endDate": "<string>",
        "extraData": [
          {
            "kvpKey": "<string>",
            "kvpType": "<string>",
            "kvpValue": "<string>"
          }
        ],
        "longForm": "<string>",
        "postalCode": "<string>",
        "region": "<string>",
        "startDate": "<string>",
        "state": "<string>",
        "streetName": "<string>",
        "streetNumber": "<string>",
        "streetType": "<string>",
        "suburb": "<string>",
        "town": "<string>",
        "unitNumber": "<string>",
        "unstructuredLongForm": "<string>"
      }
    ],
    "dateOfBirth": {
      "country": "<string>",
      "dateOfBirth": "<string>",
      "locality": "<string>",
      "unstructuredDateOfBirth": "<string>",
      "yearOfBirth": "<string>"
    },
    "entityId": "<string>",
    "entityProfile": "<string>",
    "entityType": "<string>",
    "extraData": [
      {
        "kvpKey": "<string>",
        "kvpType": "<string>",
        "kvpValue": "<string>"
      }
    ],
    "flags": [
      {
        "flag": "<string>",
        "value": 123
      }
    ],
    "gender": "<string>",
    "identityDocs": [
      {
        "country": "<string>",
        "createdFromScan": true,
        "docScan": [
          {
            "ScanDelete": true,
            "scanCreated": "<string>",
            "scanData": "<string>",
            "scanDataRetrievalState": "<string>",
            "scanDocId": "<string>",
            "scanFilename": "<string>",
            "scanMIME": "<string>",
            "scanPageNum": 123,
            "scanSide": "<string>",
            "scanType": "<string>"
          }
        ],
        "documentId": "<string>",
        "documentStatus": "<string>",
        "extraData": [
          {
            "kvpKey": "<string>",
            "kvpType": "<string>",
            "kvpValue": "<string>"
          }
        ],
        "idExpiry": "<string>",
        "idIssued": "<string>",
        "idNumber": "<string>",
        "idSubType": "<string>",
        "idType": "<string>",
        "manuallyModified": true,
        "region": "<string>"
      }
    ],
    "name": {
      "displayName": "<string>",
      "familyName": "<string>",
      "givenName": "<string>",
      "honourific": "<string>",
      "middleName": "<string>"
    },
    "organisationData": {
      "adverseCreditDataPresent": true,
      "aliases": [
        "<string>"
      ],
      "blockingReasons": [
        {
          "candidates": [
            {
              "address": "<string>",
              "code": "<string>",
              "countryIso": "<string>",
              "registeredName": "<string>",
              "registryDescription": "<string>",
              "subdivision": "<string>"
            }
          ],
          "description": "<string>",
          "type": "<string>"
        }
      ],
      "class": {
        "code": "<string>",
        "description": "<string>"
      },
      "contactDetails": {
        "email": "<string>",
        "faxNumber": "<string>",
        "telephoneNumber": "<string>",
        "websiteURL": "<string>"
      },
      "disclosingEntityIndicator": true,
      "includesNonBeneficiallyHeld": true,
      "industryCodes": [
        {
          "code": "<string>",
          "description": "<string>"
        }
      ],
      "industryDeclarations": [
        {
          "description": "<string>",
          "language": "<string>"
        }
      ],
      "kycCustomerType": "<string>",
      "lastCheckDate": "<string>",
      "legalFormDetails": {
        "basis": "<string>",
        "capital": "<string>",
        "comments": "<string>",
        "control": "<string>",
        "incorp": "<string>",
        "partner": "<string>",
        "responsibility": "<string>",
        "stocks": "<string>"
      },
      "normalisedLegalStatus": "<string>",
      "ownershipResolved": true,
      "registeredName": "<string>",
      "registration": {
        "countryIso": "<string>",
        "date": "<string>",
        "number": "<string>",
        "previousNumber": "<string>",
        "registryCode": "<string>",
        "registryDescription": "<string>",
        "state": "<string>",
        "unstructuredDate": "<string>",
        "unstructuredFoundationDate": "<string>"
      },
      "registries": {
        "abr": {
          "abn": "<string>",
          "acn": "<string>",
          "addresses": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>",
              "postcode": "<string>",
              "stateCode": "<string>"
            }
          ],
          "businessNames": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>",
              "name": "<string>",
              "type": "<string>"
            }
          ],
          "charityEndorsements": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>",
              "type": "<string>"
            }
          ],
          "charityTypes": [
            {
              "description": "<string>",
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>"
            }
          ],
          "description": "<string>",
          "dgrEndorsements": [
            {
              "endorsedFrom": "<string>",
              "endorsedTo": "<string>"
            }
          ],
          "gst": [
            {
              "effectiveFrom": "<string>",
              "effectiveTo": "<string>"
            }
          ],
          "historicalChanges": [
            {
              "businessName": [
                "<string>"
              ],
              "date": "<string>",
              "entityStatus": [
                "<string>"
              ],
              "goodsAndServicesTax": [
                "<string>"
              ],
              "mainBusinessPhysicalAddress": [
                "<string>"
              ],
              "mainName": [
                "<string>"
              ],
              "mainTradingName": [
                "<string>"
              ]
            }
          ],
          "lastUpdated": "<string>",
          "name": "<string>",
          "registeredDate": "<string>",
          "status": "<string>",
          "statusEffectiveFrom": "<string>",
          "type": "<string>",
          "typeCode": "<string>",
          "updatedDate": "<string>"
        }
      },
      "reviewDate": "<string>",
      "shareStructure": [
        {
          "amountDue": 123,
          "amountPaid": 123,
          "classCode": "<string>",
          "classTitle": "<string>",
          "docNumber": "<string>",
          "docNumberQualifier": "<string>",
          "sharesIssued": 123,
          "status": "<string>"
        }
      ],
      "startDate": "<string>",
      "status": {
        "code": "<string>",
        "description": "<string>"
      },
      "subType": {
        "code": "<string>",
        "description": "<string>"
      },
      "subclass": {
        "code": "<string>",
        "description": "<string>"
      },
      "type": {
        "code": "<string>",
        "description": "<string>"
      }
    }
  },
  "status": "<string>"
}

Authorizations

​
api_key
string
header
required

API key issued by FrankieOne. This will rotate regularly

Headers

​
X-Frankie-CustomerID
string
required

Customer ID issued by Frankie Financial. This will never change. Your API key, which is mapped to this identity, will change over time

​
X-Frankie-CustomerChildID
string

If, as a Frankie Customer, you are acting on behalf of your own customers, then you can populate this field with a Frankie-assigned ID. Note: If using a CustomerChildID, you will also need a separate api_key for each child. Any documents, checks, entities that are created when this field has been populated will now be tied to this CustomerID + CustomerChildID combination. Just as Customers cannot see data created by other Customers, so too a Customer's Children will not be able to see each other's data. A Customer can see the documents/entities and checks of all their Children

​
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

Body

application/json

Photo of the identity document to be used, and any known details about the associated document or entity

​
digital
boolean

Is this a digital version of the id, eg Digital Driver Licence screenshot

Example:

true

​
documentId
string

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

​
entity
object
​
fileData
object
​
token
string

if no entity has yet been created for this idv check, pass through the token instead

Response

OK

​
entity
object
​
status
string