KYC API EndpointsDocument

Search For a Document

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.

Authentication

api_keystring
API Key authentication via header

Headers

X-Frankie-CustomerIDstringRequiredformat: "uuid"
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-CustomerChildIDstringOptionalformat: "uuid"
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

A document object with the parameters you wish to search on.
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.
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
documentIdstringOptionalformat: "uuid"

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
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.
Allowed values:
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)

idExpirystringOptionalformat: "date"

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

idIssuedstringOptionalformat: "date"

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.

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.
requestIdstringformat: "ulid"

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 objects or null
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)

Errors