KYCImplementation Guide

Executing a Workflow

A step-by-step guide to executing a verification workflow and interpreting the results.

Overview

Executing a workflow is the core action in the FrankieOne platform. It takes an existing individual entity and runs them through a pre-configured series of checks (e.g., KYC, AML, IDV) to return a final verification status.

This guide will walk you through the end-to-end process of executing a workflow and understanding its result.

The Workflow Execution Lifecycle

The process follows a simple, synchronous pattern. For most web-based onboarding, the result is returned in a few seconds.

1

1. You Initiate the Workflow

You send a POST request to the /execute endpoint for a specific entity and workflow. This tells FrankieOne to begin the verification process.

2

2. FrankieOne Performs the Checks

Our platform contacts all the necessary third-party data sources (e.g., government databases, credit bureaus, watchlist providers) as defined in your workflow rules.

3

3. You Receive the Result

The API response to your initial POST request contains the complete workflowResult object. This object holds the final status and all the detailed outcomes of the checks performed.

Implementation Guide

Prerequisites

Before executing a workflow, ensure you have:

  • An entityId for the individual you want to verify.
  • The serviceName of the Service Profile they are being assessed against (e.g., KYC).
  • The workflowName of the specific workflow you want to run (e.g., Standard-KYC-AU).

Step 1: Execute the Workflow

To trigger the workflow, make a POST request to the execute endpoint, including the entityId, serviceName, and workflowName in the path.

cURL
1curl --location --request POST '[https://api.frankieone.com/v2/individuals/](https://api.frankieone.com/v2/individuals/){{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute' \
2--header 'api_key: {{your_api_key}}' \
3--header 'X-Frankie-CustomerID: {{your_customer_id}}'

Step 2: Understand the Response

The response body contains the workflowResult object. This is a rich object with everything you need to know about the verification outcome.

JSON Response
1{
2  "requestId": "req_01JBH9XJ4Z5Y6W7R8S9T0V1A2B",
3  "workflowResult": {
4    "workflowExecutionId": "wfe_01JBH9XK5C6D7E8F9G0H1J2K3L",
5    "workflowExecutionState": "COMPLETED",
6    "status": "PASS",
7    "result": "PASS",
8    "riskAssessment": {
9      "riskLevel": "LOW",
10      "riskScore": 10,
11      "riskFactors": [...]
12    },
13    "issues": [],
14    "workflowStepResults": [...]
15  },
16  "individual": {...}
17}

To make an automated decision, you should parse the key fields within the workflowResult.

  • status: This is the most important field. The most common values are PASS, FAIL, or REVIEW. This field incorporates any manual overrides and represents the final state.
  • workflowExecutionState: This must be COMPLETED. If it shows ERROR or TIMEOUT, the workflow did not finish, and the status should not be trusted.
  • result: This represents the original, automated outcome of the workflow before any manual changes. It’s useful for auditing.
Common Step (stepName)Common Outcome (result)Meaning
KYCMATCH / NO_MATCHA match was (or was not) found against KYC data sources.
AMLCLEAR / HITNo matches (or a potential match) was found on AML watchlists.
IDVMATCH / NO_MATCHAn identity document was (or was not) successfully verified.

Advanced: Overriding a Result

In some cases, a compliance officer may need to manually override a workflow’s automated result. This is achieved by making a PATCH request to the specific workflow execution.

HTTP
1PATCH /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}

Provide the new status and an optional comment to explain the reason for the change. This action is fully audited.

JSON Request
1{
2  "status": "PASS",
3  "comment": {
4    "text": "Manually approved by compliance officer John Doe after reviewing supporting documents."
5  }
6}