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:

Address object:

Document 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:

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:

The Scan object represents the scan details of the captured document.

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:

JavaScript

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

This object contains the results of different checks. More complete details can be retrieved via direct API calls.

The Issue object

The issue object represents an issue found during the entity verification process.

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:

1. Set a Customer Reference: A unique, immutable identifier for an applicant.
2. 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.