Manual KYC Verification (mKYC)

What is Manual KYC?

Manual KYC (mKYC) is the process of verifying a customer’s identity using physical documents that are sighted and confirmed by an authorised representative (e.g., during a face-to-face meeting).

This guide explains how to use the FrankieOne API to record the outcome of a manual verification, ensuring it is correctly reflected in your compliance workflows and audit trails.

How It Works: The FrankieOne Approach

FrankieOne facilitates mKYC through a simple two-part process that separates the recording of the approval from the verification check itself.

Implementation Guide

This guide will walk you through the API calls required to perform a manual KYC verification.

Prerequisites

Before you begin, ensure you have the following:

1. An existing entityId for the individual you want to verify.
2. The entity has all the necessary information and documents (e.g., name, address, date of birth, and document details with documentIds) already added to their profile via the API.
3. A workflow has been configured in your FrankieOne instance that includes the Manual KYC step.

Step 1: Log the Manual Approval

First, you must log that the manual verification has taken place. You do this by calling the POST /v2/individuals/{entityId}/results/mkyc endpoint. This request tells FrankieOne to create the special “Manual” Process Results (PROs) that will be used as evidence in the workflow.

1
curl --location 'https://api.frankie.one/v2/individuals/{{entityId}}/results/mkyc' \
2
--header 'api_key: {{your_api_key}}' \
3
--header 'X-Frankie-CustomerID: {{your_customer_id}}' \
4
--header 'Content-Type: application/json' \
5
--data '{
6
    "approvedBy": "Jane Doe (Officer #1234)",
7
    "approvedDocuments": [
8
        "doc_01HBFB8W6A7E8F9G0H1J2K3L4M"
9
    ],
10
    "comment": {
11
        "text": "Customer presented passport in person at Melbourne branch."
12
    }
13
}'

Request Body Explained:

• approvedBy: (string) The name or identifier of the person who performed the manual verification. This is crucial for your audit trail.
• approvedDocuments: (array of strings) A list of the documentIds that were sighted and approved as part of the check.
• comment: (object, optional) A comment to add context to the approval.

A successful request will return a 200 OK response containing the newly created PROs. Note the key fields that identify these as manual results: providerResult.name is set to MANUAL and result is MATCH.

Step 2: Execute the Verification Workflow

With the manual approval logged, you can now execute your standard verification workflow. The Manual KYC step in this workflow will automatically detect the PROs created in Step 1 and pass if your configured rules are met.

1
curl --location --request POST 'https://api.frankie.one/v2/individuals/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute' \
2
--header 'api_key: {{your_api_key}}' \
3
--header 'X-Frankie-CustomerID: {{your_customer_id}}'

In the workflow execution response, you will see the Manual KYC step result. Look for provider: "MANUAL" and a result of MATCH or PASS to confirm success.

Configuring the Manual KYC Step

The logic that determines a successful manual verification is defined within the Manual KYC workflow step, not in the API call. The API call simply logs the evidence (approvedDocuments); the workflow step evaluates that evidence against your business rules.

Below is an example of a policy configuration within a workflow step.

1
{
2
  "requirements": [
3
    {"name": 1, "dateOfBirth": 1, "primaryPhotographic": 1},
4
    {"name": 1, "address": 1, "primaryPhotographic": 1},
5
    {"name": 1, "dateOfBirth": 1, "address": 1, "primaryNonPhotographic": 2},
6
    {"name": 1, "dateOfBirth": 1, "address": 1, "primaryNonPhotographic": 1, "secondary": 1}
7
  ],
8
  "countries": {
9
    "AUS": [
10
      {
11
        "type": "primaryPhotographic",
12
        "documentTypes": ["DRIVERS_LICENSE", "PASSPORT"]
13
      },
14
      {
15
        "type": "primaryNonPhotographic",
16
        "documentTypes": ["BIRTH_CERT", "CITIZENSHIP_CERT"]
17
      },
18
      {
19
        "type": "secondary",
20
        "documentTypes": ["UTILITY_BILL", "BANK_STATEMENT"]
21
      }
22
    ]
23
  }
24
}

In this example, to manually approve an Australian entity, you could satisfy the first requirement by logging an approval with a single documentId that corresponds to a PASSPORT.

Invalidating Manual Results

If you need to revert a manual approval (e.g., to perform a new electronic check), you can invalidate all existing manual results for an entity.

Call the POST /v2/individuals/{entityId}/results/mkyc/invalidate endpoint. This will mark all existing manual PROs as MARKED_INVALID, causing any subsequent Manual KYC workflow steps to fail until a new manual approval is logged.

1
curl --location --request POST 'https://api.frankie.one/v2/individuals/{{entityId}}/results/mkyc/invalidate' \
2
--header 'api_key: {{your_api_key}}' \
3
--header 'X-Frankie-CustomerID: {{your_customer_id}}'