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 nameDescription
'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:
PropertyType
addressIdstring
postalCodestring
statestring
townstring
suburbstring
countryChar3CountryCode
Document object:
PropertyType
documentIdstring
idType'PASSPORT' or 'DRIVERS_LICENCE'
countryChar3CountryCode
idNumberstring
extraDataThe hash of document-specific fields.
ocrResultOCRResult object (optional)
scansArray of Scan objects
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:

PropertyType
ocrDatetimeDateTimeString
statusOCRStatus
mismatchOCRExtractedFields[]
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:

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

PropertyType
scanIdstring
mimeTypestring
scanNamestring
side'F' or 'B'
scanCreatedDateTime 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

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

PropertyTypeDescription
checkTypesstring[]An array of strings describing the types of checks that were performed.
checkDateDateTimeString
statusobjectAn object describing the entity's overall status.
status.type'failed', 'passed', 'fail_manual', 'pass_manual', 'refer', 'wait', 'unchecked', 'archived' or 'inactive'
riskobjectAn object containing the risk level.
risk.levelnumberThe entity's overall risk level.
alertListArray of Issue objects.
checkCounts
checkCounts.nameArray of Source
checkCounts.dobArray of Source
checkCounts.addresskey is an address ID and each value is the address check count.
checkCounts.address[addressId]Array of Source
checkCounts.documentkey is a document ID and each value is the document check count.
checkCounts.document[documentId]Array of Source
personalChecksobject
personalChecks.nameboolean | null
personalChecks.dateOfBirthboolean | null
personalChecks.phoneNumberboolean | null
personalChecks.emailboolean | null
personalChecks.addressesobjectA hash, where each key is an address ID and each value is the address check result.
personalChecks.addresses[addressId]boolean | null

The Issue object

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

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

  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.