Individual Details
The following sections will help you set up OneSDK for your KYC implementation needs.
Capturing details from an individual
Each OneSDK instance starts with a session tied to the user being onboarded. If the user is already an Entity in FrankieOne, OneSDK loads their existing data, enabling seamless experiences across sessions. If the user is new, no data is loaded.
Initialize OneSDK for a new user
To onboard a new user, assign a unique customer reference when creating the session object. This reference will be tied to the newly created entity on the FrankieOne platform.
The following example creates a session object for a user using a customer reference.
ENCODED_CREDENTIAL=$(echo -ne "$YOUR_CUSTOMER_ID:$API_KEY" | base64);
curl https://backend.demo.frankiefinancial.io/auth/v1/machine-session \
-X POST \
-H "Authorization: machine $ENCODED_CREDENTIAL"
-H 'Content-Type: application/json' \
-d '{
"permissions": {
"preset": "one-sdk",
"reference": "YOUR_CUSTOMER_REFERENCE",
}
}';
Initialize OneSDK for an existing user
You can also create an entity in FrankieOne upfront, and use the entity ID to create the session.
ENCODED_CREDENTIAL=$(echo -ne "$YOUR_CUSTOMER_ID:$API_KEY" | base64);
curl https://backend.demo.frankiefinancial.io/auth/v1/machine-session \
-X POST \
-H "Authorization: machine $ENCODED_CREDENTIAL"
-H 'Content-Type: application/json' \
-d '{
"permissions": {
"preset": "one-sdk",
"entityId": "ENTITY_ID_FROM_FRANKIE_ONE",
}
}';
Access the user's information
Obtain the individual
object from the OneSDK instance you initialised.
const config = {
dummy: true // remove this in production
}
const oneSdk = await OneSdk(config);
const individual = oneSdk.individual();
Personal information about the user can be accessed using the access(fieldName)
method. This method returns a handler to get access to the given field.
Get and set values
You can obtain a getter and setter for each field using the individual.access(fieldName)
method.
The following example obtains the name field getter and setter and then updates the values.
const { getValue, setValue } = individual.access('name');
// Get the current values
const { givenName, familyName } = getValue()
// Update the user with new values
setValue({
givenName: "Albert",
familyName: "Einstein",
middleName: "J"
})
Subscribe to changes
The access(fieldName)
method also returns an RXJS.Observable object that allows you to subscribe to changes to the field's value for building reactive applications.
const { observable } = individual.access("name");
observable.subscribe(newName => {
// update your interface with the new value
});
All fields
The supported fields you can get access to are:
Field name | Description |
---|---|
'entityId' | string |
'name' | { givenName, middleName, familyName } |
'dateOfBirth' | string |
'consentsGiven' | An array of consent keywords string[] that need to be provided before submission |
'addresses' | Array of Address objects associated with the individual. See table below. |
'documents' | ocrResult?: {Described later}, scans: Scan[] }` |
'hasLoaded' | boolean |
Address
object:
Address
object:Property | Type |
---|---|
addressId | string |
postalCode | string |
state | string |
town | string |
suburb | string |
country | Char3CountryCode |
Document
object:
Document
object:Property | Type |
---|---|
documentId | string |
idType | 'PASSPORT' or 'DRIVERS_LICENCE' |
country | Char3CountryCode |
idNumber | string |
extraData | The hash of document-specific fields. |
ocrResult | OCRResult object (optional) |
scans | Array of Scan objects |
OCRResult
object:
OCRResult
object:The OCRResult
object contains the data extracted from a document image. It includes fixed and variable properties depending on the extracted data.
Fixed properties:
Property | Type |
---|---|
ocrDatetime | DateTimeString |
status | OCRStatus |
mismatch | OCRExtractedFields[] |
documentType | 'PASSPORT' | 'DRIVERS_LICENSE' |
Variable properties:
The OCRResult object will vary based on what was extracted. For example:
{
...,
documentTypeInternal: "DRIVERS_LICENCE",
dateOfExpiry: "2031-05-28",
dateOfIssue: "2021-05-28",
documentType: "DRIVERS_LICENCE",
documentNumber: "999999999",
dateOfBirth: "1990-01-01",
issuingCountry: "AUS",
state: "VIC",
postcode: "3000",
town: "Melbourne",
street: "80 Collins Street",
firstName: "PETER",
lastName: "TESTTHIRTEEN",
}
The Scan
object:
Scan
object:The Scan object represents the scan details of the captured document.
Property | Type |
---|---|
scanId | string |
mimeType | string |
scanName | string |
side | 'F' or 'B' |
scanCreated | DateTime string |
Submit changes to an individual's details
When you update the details of an individual using OneSDK, the changes are stored locally but are not submitted automatically.
Use the submit()
method to persist the details in the FrankieOne platform.
await individual.submit();
Verify an individual
Note
Make sure you have captured consent from the user before the submit and verify steps. You would need to add consent to the
individual
object as follows:individual.addConsent("general"); individual.addConsent("docs"); individual.addConsent("creditheader");
You may also request checks to be run with the optional parameter { verify: true }
. The submit method will return a CheckSummary
object in this case.
const checkResults = await individual.submit({
verify: true
});
The CheckSummary
object
CheckSummary
objectThis object contains the results of different checks. More complete details can be retrieved via direct API calls.
Property | Type | Description |
---|---|---|
checkTypes | string[] | An array of strings describing the types of checks that were performed. |
checkDate | DateTimeString | |
status | object | An object describing the entity's overall status. |
status.type | 'failed' , 'passed' , 'fail_manual' , 'pass_manual' , 'refer' , 'wait' , 'unchecked' , 'archived' or 'inactive' | |
risk | object | An object containing the risk level. |
risk.level | number | The entity's overall risk level. |
alertList | Array of Issue objects. | |
checkCounts | ||
checkCounts.name | Array of Source | |
checkCounts.dob | Array of Source | |
checkCounts.address | key is an address ID and each value is the address check count. | |
checkCounts.address[addressId] | Array of Source | |
checkCounts.document | key is a document ID and each value is the document check count. | |
checkCounts.document[documentId] | Array of Source | |
personalChecks | object | |
personalChecks.name | boolean | null | |
personalChecks.dateOfBirth | boolean | null | |
personalChecks.phoneNumber | boolean | null | |
personalChecks.email | boolean | null | |
personalChecks.addresses | object | A hash, where each key is an address ID and each value is the address check result. |
personalChecks.addresses[addressId] | boolean | null |
The Issue
object
Issue
objectThe issue object represents an issue found during the entity verification process.
Property | Type | |
---|---|---|
type | 'warning' , 'alert' , 'success' , 'action' | |
term | '404' , 'partial' , 'duplicate' | A short word used to describe the issue. One of '404' , 'partial' , 'duplicate' |
Set Entity profile recipe before verifying an individual
You can set the Entity profile recipe before verifying an individual after initialising. To do so, add the following code:
const individual = onesdk.individual();
To set the profile types, use the following code,
individual.setProfileType(ProfileTypeEnumerated)
where ProfileTypeEnumerated
consists of:
'gov_id',
'gov_id_media',
'international',
'international_media',
'organisation',
'safe_harbour',
'safe_harbour_id',
'safe_harbour_id_media',
'safe_harbour_media',
'safe_harbour_plus',
'safe_harbour_plus_media',
'standard_kyc',
'under18',
'2x_bureaus_or_1_bureau_1_id',
'Citizen_NationalID',
'NonCitizen_Passport',
'NonCitizen_Passport_No_Bio',
'above18',
'aml_media_only',
'aml_only',
'asia_verify_custom_check_kyc',
'auto',
'beneficiary',
'customer',
'default',
'devicecheck',
'devicechecknostoponfail',
'devicecheckonly',
'full'
Applicant Reference Manager
This guide explains how to manage applicant references, including customer IDs and extra reference data. It ensures that rules for setting and changing references are followed to prevent system inconsistencies, particularly with session management.
Purpose
The Applicant Reference Manager allows you to:
- Set a Customer Reference: A unique, immutable identifier for an applicant.
- Add Additional References: Secondary reference data may be attached to the applicant.
Once the Customer Reference is set, it cannot be modified. This ensures that session integrity remains intact, as changing this reference could affect system operations connected to it.
Example Usage
const individual = oneSdk.individual();
// Set a customer reference
individual.addReference('customer_reference', 'customer123');
// Add a secondary reference
individual.addReference('order_id', 'order456');
In this example:
- Customer Reference: You can assign a unique customer reference (
customer123
) once. Any further attempts to change it will result in an error. - Secondary Reference: You can associate additional identifiers, such as an order ID (
order456
). If an order ID already exists for this applicant, a warning will be emitted.
Updated 2 months ago