Executing a Workflow

Overview

Executing a workflow is the core action in the FrankieOne platform. It takes an entityId and runs it through a pre-configured series of checks (e.g., KYC, AML, IDV) to return a final verification status. This is the central mechanism for assessing risk and making onboarding decisions.

This guide covers the primary methods for executing a workflow and provides a high-level overview of how to handle the response.

Workflow Execution Patterns

There are two primary patterns for executing a workflow, depending on whether the individual already exists in your system.

1. Execute for an Existing Entity

This is the most common pattern. If you have already created an individual and have their entityId, you can execute a workflow against them at any time.

Use Cases:

• Running an initial KYC check after a user has signed up.
• Re-running a workflow after a user has updated their information.
• Performing periodic or event-driven reviews.

2. Create and Execute for a New Entity

For new user onboarding, you can create the individual entity and execute a workflow in a single API call. This is a highly efficient pattern that streamlines the initial verification process.

Use Cases:

• Onboarding a new customer who has just filled out a registration form.
• Verifying a user for the first time as part of a single, atomic transaction.

Implementation Guide

Prerequisites

Before executing a workflow, ensure you have:

• The entityId for the individual (unless using the “Create and Execute” pattern).
• 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

Choose the endpoint that matches your execution pattern.

For an Existing Entity:

Make a POST request to the execute endpoint, including the entityId, serviceName, and workflowName in the path.

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

For a New Entity:

Make a POST request to the new execute endpoint, providing the individual’s data in the request body.

1
curl --location --request POST '[https://api.frankie.one/v2/individuals/new/serviceprofiles/](https://api.frankie.one/v2/individuals/new/serviceprofiles/){{serviceName}}/workflows/{{workflowName}}/execute' \
2
--header 'api_key: {{your_api_key}}' \
3
--header 'X-Frankie-CustomerID: {{your_customer_id}}' \
4
--data '{
5
    "individual": {
6
        "name": { "givenName": "John", "familyName": "Doe" },
7
        "dateOfBirth": { "year": "1990", "month": "01", "day": "25" },
8
        "..." : "..."
9
    }
10
}'

Step 2: Interpret the High-Level Response

The API response will contain the workflowResult object. For automated decision-making, you should parse these key top-level fields:

• workflowExecutionState: This must be COMPLETED. If it shows ERROR or TIMEOUT, the workflow did not finish, and the status should not be trusted.
• 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, authoritative state.
• result: This represents the original, automated outcome of the workflow before any manual changes. It’s useful for auditing.

Advanced: Asynchronous Execution

For workflows that may take longer to complete, you can request asynchronous execution by including the X-Frankie-Background: 1 header.

• The API will immediately respond with a 202 Accepted status and a requestId.
• The workflow will continue to process in the background.
• You will be notified of the final result via a configured webhook.

This pattern is useful for preventing timeouts in client-facing applications.

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.

1
PATCH /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.

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

Next Steps

Once you have successfully executed a workflow, the next critical step is to parse the rich workflowResult object to understand the outcome of every check.

For a complete breakdown of every field in the response, refer to our detailed guide: Interpreting Workflow Results.

Additional Resources

• FrankieOne API Reference
• FrankieOne Support