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 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
        "gender": {
17
            "gender": "FEMALE"
18
        },
19
        "nationality": "AUS",
20
        "addresses": [
21
            {
22
                "type": "RESIDENTIAL",
23
                "streetName": "NINGALOO",
24
                "streetNumber": "12",
25
                "streetType": "STREET",
26
                "locality": "EXMOUTH",
27
                "subdivision": "WA",
28
                "country": "AUS",
29
                "postalCode": "6707"
30
            }
31
        ],
32
        "documents": {
33
            "IDENTITY": [
34
              {
35
                "type": "PASSPORT",
36
                "primaryIdentifier": "P52184975",
37
                "country": "AUS"
38
              }
39
            ]
40
        },
41
        "consents": [
42
            { "type": "GENERAL" },
43
            { "type": "DOCS" }
44
        ]
45
    }
46
}'

A successful 201 response will contain the full entity profile, including the unique entityId.

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. Below is a breakdown of the key sections from the example response.

1
{
2
  "individual": {
3
    "entityId": "99f16410-2613-4181-8cf1-048625900013",
4
    "name": { "displayName": "MARY TESTFOURTEEN", ... },
5
    ...
6
  },
7
  "requestId": "01JZHEX0WX2QEM6EY139D5NNP1",
8
  "workflowResult": {
9
    "workflowExecutionId": "01JZHEX5FQA4DJB0MMJFZR26JS",
10
    "workflowExecutionState": "COMPLETED",
11
    "status": "PASS",
12
    "riskAssessment": {
13
      "riskLevel": "LOW",
14
      "riskScore": 12,
15
      "riskFactors": [ { "factor": "entity_type", ... }, { "factor": "entity_age", ... } ]
16
    },
17
    "steps": {
18
      "passed": [ "START", "MATCHLIST", "IDV", "KYC", "AML", "DECISION", "FINISH" ],
19
      ...
20
    },
21
    "issues": [],
22
    "workflowStepResults": [
23
      {
24
        "stepName": "KYC",
25
        "result": "MATCH",
26
        "summary": {
27
          "matchedRules": [
28
            {
29
              "ruleName": "gov_id_only",
30
              "isVerified": true,
31
              "matchCount": 3,
32
              "matchDetails": [
33
                {
34
                  "provider": "con_testbed-docs",
35
                  "source": "au-govid1-pp",
36
                  "attributesMatched": [ "dateOfBirth", "govId", "name" ]
37
                }
38
              ]
39
            }
40
          ]
41
        },
42
        ...
43
      },
44
      ...
45
    ]
46
  }
47
}

This section explains the most important fields for determining the outcome. For a full reference of every field, see the Interpreting Workflows guide.

• status: This is the definitive recommendation. The most common values are PASS, FAIL, or REVIEW.
• result: This represents the original, unaltered outcome of the workflow before any manual overrides. It’s useful for auditing.
• 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.

To understand the KYC step in detail, inspect its summary.matchedRules object. This shows which data sources were used (matchSources) and if the verification criteria were met (isVerified: true).

• riskLevel: The final risk rating (e.g., LOW, MEDIUM, HIGH).
• riskScore: The numerical score that corresponds to the risk level.
• riskFactors: An array of the specific reasons (e.g., entity_age, country) that contributed to the score.

Best Practices for Integration

Trust the status field as the final, authoritative outcome of the verification.

• 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 will tell them where to look.