> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manual KYC Verification (mKYC)

> A step-by-step guide to verifying an entity that has completed an in-person or offline identity check.

## 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.

<Steps>
  <Step title="1. Log the Manual Approval via API">
    You make a single API call to create special "Manual" **Process Results** for an entity. This acts as a permanent record that a trusted employee has verified the customer's identity documents in person.
  </Step>

  <Step title="2. Verify via Workflow">
    A dedicated `Manual KYC` step within your configured workflow checks for the existence of these "Manual" Process Results. If they are present and meet your configured policy, the step passes, allowing the entity to proceed through the workflow just like an electronic verification.
  </Step>
</Steps>

***

## 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 `documentId`s) 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.

```bash cURL theme={null}
  curl --location 'https://api.frankie.one/v2/individuals/{{entityId}}/results/mkyc' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}' \
  --header 'Content-Type: application/json' \
  --data '{
      "approvedBy": "Jane Doe (Officer #1234)",
      "approvedDocuments": [
          "doc_01HBFB8W6A7E8F9G0H1J2K3L4M"
      ],
      "comment": {
          "text": "Customer presented passport in person at Melbourne branch."
      }
  }'
```

**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 `documentId`s 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.

```bash cURL theme={null}
  curl --location --request POST 'https://api.frankie.one/v2/individuals/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute' \
  --header 'api_key: {{your_api_key}}' \
  --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.

```json JSON theme={null}
{
  "requirements": [
    {"name": 1, "dateOfBirth": 1, "primaryPhotographic": 1},
    {"name": 1, "address": 1, "primaryPhotographic": 1},
    {"name": 1, "dateOfBirth": 1, "address": 1, "primaryNonPhotographic": 2},
    {"name": 1, "dateOfBirth": 1, "address": 1, "primaryNonPhotographic": 1, "secondary": 1}
  ],
  "countries": {
    "AUS": [
      {
        "type": "primaryPhotographic",
        "documentTypes": ["DRIVERS_LICENSE", "PASSPORT"]
      },
      {
        "type": "primaryNonPhotographic",
        "documentTypes": ["BIRTH_CERT", "CITIZENSHIP_CERT"]
      },
      {
        "type": "secondary",
        "documentTypes": ["UTILITY_BILL", "BANK_STATEMENT"]
      }
    ]
  }
}
```

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.

```bash cURL theme={null}
  curl --location --request POST 'https://api.frankie.one/v2/individuals/{{entityId}}/results/mkyc/invalidate' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}'
```