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

# Electronic KYC with Government ID

> A step-by-step guide to verifying a customer's identity electronically using their personal information and a government-issued ID.

## What is an Electronic KYC (eKYC) Check?

An electronic Know Your Customer (eKYC) check is the standard process for verifying a customer's identity against digital data sources. This guide focuses on a common and robust method: verifying a customer's personal information (name, DOB, address) along with a government-issued identity document.

This process is fundamental to meeting your compliance obligations under regulations like Australia's Anti-Money Laundering and Counter-Terrorism Financing (AML/CTF) Act, which requires matching customer data against reliable and independent sources.

## How It Works

The process involves two main API interactions:

<Steps>
  <Step title="1. Create an Entity Profile">
    First, you create a complete digital profile of your customer by sending their personal details and government ID information to the FrankieOne API. This creates a unique `entityId` for the customer.
  </Step>

  <Step title="2. Execute a KYC Workflow">
    Next, you trigger a pre-configured workflow using the `entityId`. This workflow takes the entity's data and securely checks it against trusted third-party sources, such as the Australian Government's Document Verification Service (DVS) and credit bureaus, to find matches.
  </Step>
</Steps>

***

## Implementation Guide

This guide will walk you through the API calls required to perform a standard eKYC verification.

### Step 1: Create an Individual with a Government ID

To begin, create an entity by calling the `POST /v2/individuals` endpoint. The request below shows how to create an individual with a name, date of birth, address, an Australian Passport, and the necessary consents.

```curl cURL theme={null}
  curl --location '[https://api.frankie.one/v2/individuals](https://api.frankie.one/v2/individuals)' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}' \
  --header 'Content-Type: application/json' \
  --data '{
      "individual": {
          "name": {
              "givenName": "MARY",
              "familyName": "TESTFOURTEEN"
          },
          "dateOfBirth": {
              "year": "1963",
              "month": "01",
              "day": "01"
          },
          "addresses": [
              {
                  "type": "RESIDENTIAL",
                  "streetName": "NINGALOO",
                  "streetNumber": "12",
                  "streetType": "STREET",
                  "locality": "EXMOUTH",
                  "subdivision": "WA",
                  "country": "AUS",
                  "postalCode": "6707"
              }
          ],
          "documents": {
              "IDENTITY": [
                {
                  "type": "PASSPORT",
                  "primaryIdentifier": "P52184975",
                  "country": "AUS"
                }
              ]
          },
          "consents": [
              { "type": "GENERAL" },
              { "type": "DOCS" }
          ]
      }
  }'
```

A successful `201 Created` response will contain the full entity profile, including the unique `entityId`. **You must store this `entityId`** as it is required for all subsequent API calls for this individual.

### Step 2: Execute the KYC Workflow

Now, use the `entityId` from the previous step to execute your verification workflow. The `workflowName` in this example is `AUS-Basic1V-IDOnly`.

```curl HTTP  theme={null}
  curl --location --request POST '[https://api.frankie.one/v2/individuals/](https://api.frankie.one/v2/individuals/){{entityId}}/serviceprofiles/DEFAULT/workflows/AUS-Basic1V-IDOnly/execute' \
  --header 'api_key: {{your_api_key}}' \
  --header 'X-Frankie-CustomerID: {{your_customer_id}}'
```

A successful execution returns a `workflowResult` object containing the complete outcome of the verification.

### Interpreting the KYC Result

The `workflowResult` object contains rich information about the verification.

#### The High-Level Verdict

For automated decision-making, start with these top-level fields:

* **`status`**: This is the definitive recommendation. The most common values are `PASS`, `FAIL`, or `REVIEW`.
* **`workflowExecutionState`**: This must be `COMPLETED`. If it's anything else (e.g., `ERROR`, `TIMEOUT`), the workflow did not finish, and the `status` should not be trusted as final.

#### The KYC Step Details

To understand *why* the workflow passed or failed, find the `KYC` object within the `workflowStepResults` array.

* **`result`**: The outcome of the KYC step itself, typically `MATCH` or `NO_MATCH`.
* **`summary`**: A summary object explaining how the result was reached. The `matchedRules` array shows which data sources were successfully matched (`matchDetails`) and if the overall verification criteria were met (`isVerified: true`).

```json theme={null}
"workflowStepResults": [
  {
    "stepName": "KYC",
    "result": "MATCH",
    "summary": {
      "matchedRules": [
        {
          "ruleName": "gov_id_only",
          "isVerified": true,
          "matchDetails": [
            {
              "provider": "con_testbed-docs",
              "source": "au-govid1-pp",
              "attributesMatched": [ "dateOfBirth", "govId", "name" ]
            }
          ]
        }
      ]
    }
  }
]
```

***

## Best Practices for Integration

* **Trust the `status` field** as the final, authoritative outcome for your business logic.
* **Always check `workflowExecutionState`** to ensure the workflow `COMPLETED` successfully before actioning the result.
* **Log the `workflowExecutionId`** with every result. This is the key identifier for support, auditing, and debugging.
* **Build logic to handle the `REVIEW` status**. When you receive a `REVIEW`, your system should flag the case for manual investigation by a compliance officer. The `issues` array in the workflow result will tell them where to look.

## Next Steps

This guide provides a high-level overview of the eKYC result. For a complete reference of every field in the response, see the **[Interpreting Workflow Results](/docs/interpreting-workflows-v2)** guide.