Integration Information
To integrate FrankieOne KYC we need to do the following steps:Create New Entity
We need to create an entity to get an entityID and populate details. Note : You could do a verify action in this step, or you can do it in two steps. Both options are possible. We do recommend you pass through acustomer_reference when creating an entity, which is a unique identifier for your customer.
HTTP
Collect the entityID
Ensure to collect the entity ID from the response, to be able to update in subsequent calls.Update Entity
Update an entity when needed, to avoid creating a new entity every time.HTTP
Pass through consent capture
The following Extra data elements are important to pass through consent capture as per your obligations to consent. Customer reference is recommended to have alignment between your customer record and the FrankieOne entityID.Ensure correct consents are sent
Please ensure you send the correct consents; we do apply logic on our verification checks. For example, if a consent data source and we don’t receive the API consent flag for that data source we will likely reject the verification check on that data source, such as credit headers.For theunder18 consent flag, please only send this if your customer is under 18 (using DOB). If they’re 18 or older you don’t need to send this. Please ensure you read the notes on the consent page and if unclear please ask about consent.Search for Entity
In case someone is coming back into their preexisting sign up process, you can “search” for existing customers using thecustomer_reference.
It’s always best to maintain the status of a customer and update existing vs being stateless and creating new entities each time.
HTTP
JSON
Update Data
When you need to update the data in your records, you can use the FrankieOne API.Verify Checks
We recommend verifying checks to ensure the latest details are verified. Verifying checks can also be done at the Create or Update stage. If there are no changes to key attributes such as Name, DOB or Address then previous results can still be used. This applies as long as they’re still within the reasonable time period (age is a configuration for how long checks last). API references:Create and Verify Entity
Update Entity and Verify Details
HTTP
entityProfile = international, safe_harbour_id
Refer to Standard entity profile verification for a list of entity profiles available in demo.
We can also set up a custom profile as part of onboarding.
If you would like biometrics, we can also include the additional API calls. To learn more about ID verification (IDV), OCR, and biometrics integrations, vist IDV Service Flows.
Set up webhooks
It’s important to set up webhook notifications as detailed in Notifications - WebhooksSet up asynchronous Get results
The FrankieOne API will allow both synchronous and asynchronous processes to run in many operations. The choice can be made on a request-by-request basis too. By default, all functions are synchronous (with some exceptions, see Note below). However, where appropriate you can set a header flag:X-Frankie-Background: 1
This will indicate to the function that you wish to operate asynchronously. This isn’t available for all functions (such as GET functions), so check the specific documentation to be sure. To learn more, visit Asynchronous Calls (Background Processes)
Attach support docs
Use the FrankieOne API to Create New Document. You can also Update Existing Document.:Use with entityProfile
Please use with entityProfile that has support docs activated to ensure we check support docs.Get check results
You can also pull details down at any time using GET on the/entity/{entityId}/checks endpoint. Learn more on how to Retrieve Entity Verification Check Details.
Explanation of key attributes
Name
Attribute:name
JSON
Note on prompts
Ideally, there should be prompt as per the ID document.Native Name
Attribute:home_country_givenname, home_country_familyname
Local home country support is available for native script names.
Extra Data KVP on the entity records can be used.
JSON
Date of birth (DOB)
Attribute:dateOfBirth
Format: yyyy-mm-dd
We would need you to concatenate your DOB, we do have a yearofBirth, but not specifically Day or Month.
JSON
Email Address
The email address is one of the Identity Docs accepted. To learn more about using an email address as an identity document, read about Adding an Email AddressJSON
Mobile Phone
A mobile phone number is one of the identity docs accepted. To learn more about using a mobile phone number as an identity document, read about Adding a Mobile Phone NumberJSON
Document
Learn more about the document object at The Document Object.JSON
Passport
Name : Requires given, middle and family names as shown on the passport Date of Birth : Always in YYYY-MM-DD format ID Type: idType = PASSPORT Country : AUS Document Number : idNumber = The passport number Expiry Date : idExpiry = the expiry date YYYY-MM-DD format Learn more about the AUS: Passport.JSON
JSON
Drivers Licence
State : region - one of: VIC/NSW/ACT/WA/SA/NT/QLD/TAS - For Australian Drivers Licence Licence Number : idNumber = The licence number (not document number as given on some state licences - see below) Document Number : extraData KvpKey : “document_number”, KvpValue : “nnnnnnn…” This is the new document number being introduced from 1st July 2022 on Australian licences (in NSW). Learn more about AUS: Driver’s LicenceJSON
Medicare
Name : Requires given, middle initial and family names as shown on the card Date of Birth : Always in YYYY-MM-DD format ID Type : idType = NATIONAL_HEALTH_ID Country : AUS Number : idNumber = The full card number Colour : idSubType = G|B|Y (choice of Green Blue or Yellow) Expiry : idExpiry = YYYY-MM-DD (note: Green cards only have YYYY-MM so you need to append -01 for the -DD) Reference number : extraData Example:- KvpKey : “reference”,
- KvpValue : “n” ( where n is a number 1< n < 6 )
- KvpKey : “display_middle_name”,
- KvpValue : “J”
JSON
Address
Long form or structured :unitNumberstreetNumberstreetNamestreetType- drop down (see Street types in our Australia dataset - FAQ for a list) or input
VIC/NSW/ACT/WA/SA/NT/QLD/TAS
**postalCode **- 4 digits
country - AUS
Example :
Japanese :JSON
JSON
JSON