OneSDK - Individual Details
FrankieOne customers can use OneSDK to meet their KYC requirements. OneSDK replaces the need for customers to work with multiple service providers by creating an interface for integrating with different vendors consistently.
The following sections will help you set up OneSDK for your KYC implementation needs.
Capturing details from an individual
Each instance of OneSDK is initialized with a session that is associated with the user being onboarded. The user may already be represented by an Entity object in the FrankieOne platform or perhaps a new user who isn't known to FrankieOne yet. When initialising OneSDK with an existing entity, OneSDK will load any information that was previously submitted, allowing you to build continuous application experiences across multiple user sessions.
Initialize OneSDK for a new user
To onboard a new user, you can allocate a unique customer reference when creating a session object. This customer reference will be linked to the new entity created 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 provides information on how to manage applicant references, specifically customer identifiers and additional reference data. It ensures that core rules around setting and changing references are enforced to prevent system inconsistencies, especially about 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.
Considerations
For Product Managers, this system provides two key benefits:
- Data Integrity: Prevents accidental data overwrites or changes that could compromise customer sessions.
- Event Tracking: Through the event hub, your system can log and alert you when unexpected situations arise, such as attempts to change immutable data or duplicate reference entries.
For Developers, this implementation provides a straightforward, predictable API for reference management, with built-in safeguards to ensure session reliability.
Key Features
1. Customer Reference Management
- Set Once: A customer reference (such as a customer ID) can only be assigned once. After it's set, attempting to change it will result in an error.
- Immutable for Session Integrity: Prevents changes that could compromise session-specific actions or permissions, ensuring consistent behaviour throughout the user's interaction with the process.
2. Additional References
- Flexible Secondary References: You can associate other reference types with the applicant. These references can be dynamically added unless they already exist.
- Warning System: If you try to overwrite an existing secondary reference, the system will trigger a warning event via the Event Hub without making any changes. This allows developers to log and handle potential conflicts without causing interruptions.
3. Error Handling
- Immutable Customer Reference: If there is an attempt to change an already set customer reference, a
OneSDKError
is thrown, indicating that the action is not permitted. - Non-Destructive Handling of Secondary References: Conflicts are handled gracefully with warnings rather than errors for other references. This non-destructive behaviour helps avoid unnecessary disruptions.
Example Usage
const individual = oneSdk.individual();
// Set a customer reference
addReference('customer_reference', 'customer123');
// Add a secondary reference
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 18 days ago