Electronic KYC with Government 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:

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.

1
curl --location '[https://api.frankieone.com/v2/individuals](https://api.frankieone.com/v2/individuals)' \
2
--header 'api_key: {{your_api_key}}' \
3
--header 'X-Frankie-CustomerID: {{your_customer_id}}' \
4
--header 'Content-Type: application/json' \
5
--data '{
6
    "individual": {
7
        "name": {
8
            "givenName": "MARY",
9
            "familyName": "TESTFOURTEEN"
10
        },
11
        "dateOfBirth": {
12
            "year": "1963",
13
            "month": "01",
14
            "day": "01"
15
        },
16
        "addresses": [
17
            {
18
                "type": "RESIDENTIAL",
19
                "streetName": "NINGALOO",
20
                "streetNumber": "12",
21
                "streetType": "STREET",
22
                "locality": "EXMOUTH",
23
                "subdivision": "WA",
24
                "country": "AUS",
25
                "postalCode": "6707"
26
            }
27
        ],
28
        "documents": {
29
            "IDENTITY": [
30
              {
31
                "type": "PASSPORT",
32
                "primaryIdentifier": "P52184975",
33
                "country": "AUS"
34
              }
35
            ]
36
        },
37
        "consents": [
38
            { "type": "GENERAL" },
39
            { "type": "DOCS" }
40
        ]
41
    }
42
}'

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.

1
curl --location --request POST '[https://api.frankieone.com/v2/individuals/](https://api.frankieone.com/v2/individuals/){{entityId}}/serviceprofiles/KYC/workflows/AUS-Basic1V-IDOnly/execute' \
2
--header 'api_key: {{your_api_key}}' \
3
--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).

1
"workflowStepResults": [
2
  {
3
    "stepName": "KYC",
4
    "result": "MATCH",
5
    "summary": {
6
      "matchedRules": [
7
        {
8
          "ruleName": "gov_id_only",
9
          "isVerified": true,
10
          "matchDetails": [
11
            {
12
              "provider": "con_testbed-docs",
13
              "source": "au-govid1-pp",
14
              "attributesMatched": [ "dateOfBirth", "govId", "name" ]
15
            }
16
          ]
17
        }
18
      ]
19
    }
20
  }
21
]

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