Search For a Document

POST

Search for an existing document that matches the criteria supplied

There are of course limits to what can be searched upon. For a document search to work, you must supply at a minimum:

  • idType
  • country
  • idNumber

The service will return a list of matching documents with confidence levels.

If you are the “owner” of the document - i.e. the same CustomerID and CustomerChildID (if relevant) - then the full details of the document will be returned, except for the contents of any attached scans. If you are not the owner of the document, then just the ID and confidence level is returned. You can still use this ID to retrieve any check results (see GET /document/{documentId}/checks)

Note: At this time, we cannot perform searches on document scans. But, you can supply extraData KVPs if they’re known. These will help double check search results with ambiguous results.

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. Returns a list of potentially matching documents or document references, along with a confidence level in the match.

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.

documentSearchResultslist of objectsOptional

The list of (potentially) matching documents with confidence levels.

If you are the “owner” of the document - i.e. the same CustomerID and CustomerChildID (if relevant) - then the full details of the document will be returned, except for the contents of any attached scans. If you are not the owner of the document, then just the ID and confidence level is returned. You can still use this ID to retrieve any check results (see GET /document/{documentId}/checks)

Retrieve Document Details
Built with