User ID verification by SDK

Fraud is always spearheading. Luckily, so is our technology. Using the best combination of human and machine learning fraud spotting, we protect your business against the 6 key types of document fraud:
  • Forged documents
  • Counterfeit documents
  • Blank stolen documents
  • Fantasy or camouflage documents
  • Impostor or ‘look-a-like’ documents
  • Compromised documents
Conventionally, you have to rely on signals to trust a new user - on a device IP, a phone number, or credit database look-up. But these signals can also be exploited by imposters. This creates constant uncertainty, so you can’t focus on the user's experience, and instead start treating them with doubt.
nCore platform integrated with the document verification service provider called Onfido which lets your users scan a photo ID from their mobile device, before checking if it's genuine.
Please note that the Identity verification is applicable only for a user type INDIVIDUAL. In addition to that, user identity verification is only applicable for the customers who are using the SDK to upload documents.

High level identity verification steps

The high level identification verification steps are given below:
  1. 1.
    Enable tenant level settings
  2. 2.
    Create webhook i.e. IDENTITY_VERIFICATION
  3. 3.
    Create a user
  4. 4.
    Receive webhook having applicant ID and SDK token
  5. 5.
    Initialize SDK and Upload documents via Mobile SDK
  6. 6.
    Inform document uploaded successfully after a successful upload
  7. 7.
    Identification verification processing started by nCore platform
  8. 8.
    Identification verification processing finished successfully, the user is transitioned from PENDINGIDVERIFICATION to PENDINGKYC
  9. 9.
    nCore platform Inform by a webhook notification that the process is completed successfully

Step by Step process

Step by step process is given below to configure and perform a successful identification verification process.

Tenant level settings

Following are the settings that are required to be enabled at tenant level for Identity Verification.
Field Name
Field Type
This check enables the identity verification process.
Following are the checks you can request to enable at tenant level as per your business need
This parameter indicates that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. This parameter should be set to true after gaining the necessary consent, and if it's set to false the request will fail with a validation error.

Create a webhook

Now create a webhook event as “IDENTITY_VERIFICATION” for receiving a webhook event for applicant id and SDK token generation as shown below:
{ "endpoint": "", "events": [ "IDENTITY_VERIFICATION" ], "config": { "basic_auth_username": "username", "basic_auth_password": "password", "custom_headers": [ { "header_name": "apikey", "header_value": "306e38e4-54be-469f-beca-4297129289d6" } ], "created": "2012-05-04T19:42:32.987Z", "modified": "2012-05-04T19:42:32.987Z" } }

Create a user

After enabling webhook endpoint, you can create a user by sending a POST request to /users endpoint. Since the parameter require_document_verification is enabled as true at tenant level which means that the user will be created with a user status as PENDINGIDVERIFICATION.
{ "first_name": "John", "middle_name": "Anthony", "last_name": "Smith", "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57", "user_type": "INDIVIDUAL", }
The above sample is given just for reference, please refer to the API Catalog for a complete payload.
Below you can find important restrictions:
  1. 1.
    'first_name' and 'last_name' parameters are required in the user profile.
  2. 2.
    If address is provided in the user profile, then 'postal_code' and 'country' become required. You can use a postal code of "00000" for countries that do not support postal codes.
  3. 3.
    The 'postal_code' of the applicant's address. For UK postal codes, specify the value in the following format: SW4 6EH.
  4. 4.
    USA as a country is not supported ('address' > 'country').
  5. 5.
    For addresses, the following characters are forbidden: !$%^*=<>.
  6. 6.
    For names, the following characters are forbidden: ^!#$%*=<>;{}".

Receive a notification

Once the user is created successfully, you will receive a webhook notification along with the following details as given below:
Webhook notification sample
{ "event": "IDENTITY_VERIFICATION", "user_id": "055ef899-9650-4700-9497-e71826dd2825", "applicant_id": "generated applicant id", "sdk_token": "generated token", "note": "", "status": "PENDINGIDVERIFICATION", "old_status_reason_code": "", "status_reason_code": "I0", "status_description": "", "created": "2018-01-02T19:42:32.987Z", "modified": "2018-01-02T19:42:32.987Z" }
The system will send a webhook notification event "IDENTITY_VERIFICATION" along with a status_reason_code as "B1" if the user is not verified.
Please note that the SDK token expires in 90 mins.
To renew the SDK token, send a PUT request to /user/{id}:changeStatus endpoint with a value as “B2” in 'status_reason_code' field and ”PENDINGIDVERIFICATION” in 'status' field as shown below:
{ "status": "PENDINGIDVERIFICATION", "status_reason_code": "B2", }
Be aware that the 'status_reason_code' B2 has been added just for testing purposes, the system should not update the 'status_reason_code' from I0 to B2.

Upload the documents for verification

Now your mobile app user can start uploading the documents.
Prerequisite for this step: The integration between the mobile app user and your backend system.

Trigger user status change for a successful document upload

Once the documents are uploaded successfully, you can send a PUT request to /user/{id}:changeStatus endpoint with a value as “B0” in status_reason_code field and ”PENDINGIDVERIFICATION” in status field as shown below:
{ "status": "PENDINGIDVERIFICATION", "status_reason_code": "B0", "note": "Users documents are uploaded successfully" }

IDV re-initiation flow

Below you can find IDV re-initiation flow:
  • At first you send PUT request to /user/{id}:changeStatus endpoint to re-initiate IDV process by changing user status from PENDINGIDVERIFICATION B1, B5 or B6 to PENDINGIDVERIFICATION B2.
  • Documents are re-uploaded; then you send PUT request to /user/{id}:changeStatus endpoint to change user status from PENDINGIDVERIFICATION B2 to PENDINGIDVERIFICATION B0.
  • System will decline IDV re-initiation in case Onfido replies back with "SUSPECTED" or "REJECTED" status. In this case, user status will be updated to "TERMINATED".

Document verification internal process

nCore platform starts identity verification internally.

Receive a successful identity verification notification

Identification verification processing completed successfully, the user is transitioned from PENDINGIDVERIFICATION to PENDINGKYC and you will receive a user status change notification (if configured) as given below.
User status change notification
{ "event":"USER_STATUS_CHANGE", "User_status_change":{ "id": "cf2de83b-ac68-441b-bc54-21de60014d57", "title": "MR", "first_name": "John", "middle_name": "Anthony", "last_name": "Smith", "native_name": "John Smith", "date_of_birth": "2021-10-25T12:47:04.361Z", "email": "[email protected]", "mobile": "+551185249635", "address": { "address_line1": "Flat 1904", "address_line2": "Glass Tower", "city": "New York City", "state": "New York", "postal_code": "12345", "country": "USA" }, "gender": "MALE", "preferred_language": "EN", "place_of_birth": "Las Vegas", "nationality": "USA", "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57", "created": "2021-10-25T12:47:04.361Z", "modified": "2021-10-25T12:47:04.361Z", "country_residence": "USA", "country_tax_residence": "USA", "employment_type": "SALARIED", "employment_title": "string", "monthly_salary": 0, "company_name": "string", "company_address": { "address_line1": "Flat 1904", "address_line2": "Glass Tower", "city": "New York City", "state": "New York", "postal_code": "12345", "country": "USA" }, "company_country": "USA", "industry_type": "I01", "expected_monthly_balance": 0, "relationship_with_parent": "SON", "user_type": "INDIVIDUAL", "business_legal_name": "string", "business_dba_name": "string", "date_established": "2021-10-25T12:47:04.362Z", "phone_number": "+551185249635", "website": "string", "status": "PENDINGKYC", "status_reason_code": "I0", "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY" } }
Also you can check the status by sending a GET request to /user/{id} endpoint:
{ "id": "cf2de83b-ac68-441b-bc54-21de60014d57", "title": "MR", "first_name": "John", "middle_name": "Anthony", "last_name": "Smith", "user_type": "INDIVIDUAL", "status": "PENDINGKYC", "status_reason_code": "I0", "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY" }
The above sample is given just for reference, please refer to the API Catalog for a complete payload.