Create New Document.

POST

Create a document object. A document object can be used to simply store data around a given identity or similar document. You can attach scans, PDFs, photos, videos, etc to the object if you wish.

Headers

X-Frankie-CustomerIDstringRequired

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-CustomerChildIDstringOptional

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-ChannelstringOptional

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.

Request

This endpoint expects an object.
countrystringRequired

The ISO-3166-alpha3 country code of the issuing national. Once set, this cannot be changed.

See https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes for more

idTypeenumRequired

Valid ID types

  • ”OTHER”: Generic document type. Unspecified.
  • ”DRIVERS_LICENCE”: Driver’s licence.
  • ”PASSPORT”: Passport
  • ”VISA”: Visa document (not Visa payment card)
  • “IMMIGRATION”: Immigration card
  • ”NATIONAL_ID”: Any national ID card
  • ”TAX_ID”: Any national tax identifier
  • ”NATIONAL_HEALTH_ID”: Any national health program ID card (e.g. Medicare, NHS)
  • “CONCESSION”: State issued concession card
  • ”HEALTH_CONCESSION”: State issued health specific concession card
  • ”SENIORS_HEALTH_CONCESSION”: State issued health specific concession card for seniors
  • ”PENSION”: State issued pension ID
  • ”MILITARY_ID”: Military ID
  • ”BIRTH_CERT”: Birth certificate
  • ”CITIZENSHIP”: Citizenship certificate
  • ”MARRIAGE_CERT”: Marriage certificate
  • ”DEATH_CERT”: Death certificate
  • ”NAME_CHANGE”: Name chage confirmation
  • ”UTILITY_BILL”: Regulated utility bill, such as electricity, gas, etc
  • ”BANK_STATEMENT”: Bank/card statement
  • ”BANK_ACCOUNT”: Bank account
  • ”INTENT_PROOF”: A proof of intent. Generally a photo/video, or a scanned letter
  • ”ATTESTATION”: A document of attestation (e.g. Statutory Declaration). NOTE: these cannot be used as a supporting document
  • ”SELF_IMAGE”: A “selfie” used for comparisions
  • ”EMAIL_ADDRESS”: An email address
  • ”MSISDN”: A mobile phone number
  • ”DEVICE”: A device ID
  • ”VEHICLE_REGISTRATION”: Vehicle registration number
  • ”PROOF_OF_ADDRESS”: Can be any type of document that provides a proof of address
  • ”HOUSE_REGISTRATION”: House registration document
  • ”YELLOW_HOUSE_REGISTRATION”: Yellow House Registration Thor Ror 13
  • ”WORK_PERMIT”: Work permit
  • ”EMPLOYMENT_CERTIFICATE”: Certificate of employment
  • ”NOTARY_PUBLIC_ID”: Notary Public Identification
  • ”AVIATION_SECURITY_ID”: Aviation Security Identification
  • ”MARITIME_SECURITY_ID”: Maritime Security Identification Business related documentation
  • ”EXTERNAL_ADMIN”: Details of appointed administrator.
  • ”CHARGES”: Details of any charges that have been laid against a company or director
  • ”PRE_ASIC”: Any documents that are Pre-ASIC
  • ”ANNUAL_RETURN”: Details of a company’s annual return
  • ”REPORT”: Frankie generated report.
  • ”TRUST_DEED”: Corporate trust deed
  • ”PARTNERSHIP_AGREEMENT”: Partnership agreement documents
  • ”ADMIN_CHANGE”: Change of Administrator
  • ”COMPANY_REPORT”: ASIC filed company reports Special document types
  • ”CHECK_RESULTS”: A special document type for specifying results of checks completed other than through Frankie.
createdFromScanbooleanOptional

This document’s data was initially created from scanned and processed images. The value cannot be set manually and any attempt to do so will just be ignored.

docScanlist of objectsOptional

Collection of one or more objects that describe scan(s) that need to be put through OCR or facial recognition. These should all be from the one ID document, such as front/back, or page 1, 2, 3, etc. You can upload multiple scans in a single call, or in multiple calls.

Note: if you do upload over multiple calls, make sure you include the documentId (see above), and indicate that this is happening with a “more_data” checkAction

documentIdstringOptional

When an ID document is created/uploaded, it is assigned a documentId. You’ll see this in a successful response or successfully accepted response. This can then be referenced in subsequent calls if you’re uploading more/updated data.

documentStatusenumOptional
Allowed values: INITIALISINGSCAN_IN_PROGRESSDOC_SCANNEDDOC_CHECKED

Current status of a document.

  • ”INITIALISING”: the state whilst you’re uploading and updating
  • ”SCAN_IN_PROGRESS”: the state whilst it’s being scanned.
  • ”DOC_SCANNED”: the document has been scanned and data extracted as best as possible. It’s still possible to update the details and add more scans if you wish.
  • ”DOC_CHECKED”: the document has been used as part of a check that has been finalised in some way. You can no longer update this document and any attempt will generate an error.
extraDatalist of objectsOptional

Set of key-value pairs that provide ID type-specific data. If updating an existing document, then existing values with the same name will be overwritten. New values will be added.

If this document is scanned through OCR or similar processes, then extracted data will be found here (Some may be used to populate other fields like idNumber and idExpiry as well)

idExpirystringOptional

The expiry date of the document (if known) in YYYY-MM-DD format.

idIssuedstringOptional

The issued date of the document (if known) in YYYY-MM-DD format.

idNumberstringOptional

The ID number of the document (if known).

idSubTypestringOptional

The sub-type of identity document. Very document specific.

manuallyModifiedbooleanOptional

If this document was originally populated from scanned data, then manually adjusted (e.g. if the scan’s results weren’t 100% correct or data was missing), then this will be set to true. The value cannot be set manually and any attempt to do so will just be ignored.

regionstringOptional

Regional variant of the ID (e.g. VIC drivers licence)

You should always use the local abbreviation for this. E.g.

  • VIC for The Australian state of Victoria
  • MA for the US state of Massachusetts
  • etc

Response

The request was valid and able to be processed in some fashion. Results may or may not be successful, but it was completed as far as practical with no actual errors. Returns the document object as it stands now. No docScan file data will be returned unless the /full variant is requested.

documentobject
requestIdstring

Unique identifier for every request. Can be used for tracking down answers with technical support.

Uses the ULID format (a time-based, sortable UUID)

Note: this will be different for every request.

Create and Verify Document.
Built with