Skip to main content

​
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:
1

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

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.

​
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 --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.
HTTP
  curl --location --request POST '[https://api.frankie.one/v2/individuals/](https://api.frankie.one/v2/individuals/){{entityId}}/serviceprofiles/KYC/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).
"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 guide.