Skip to main content

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

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

You Receive the Result

The API response to your initial POST request contains the complete workflowResult object, which holds the final status and all detailed outcomes.

​
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.
cURL
    curl --location --request POST '[https://api.frankie.one/v2/individuals/](https://api.frankie.one/v2/individuals/){{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute'
    --header 'api_key: {{your_api_key}}'
    --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.
cURL
    curl --location --request POST '[https://api.frankie.one/v2/individuals/new/serviceprofiles/](https://api.frankie.one/v2/individuals/new/serviceprofiles/){{serviceName}}/workflows/{{workflowName}}/execute' 
    --header 'api_key: {{your_api_key}}'
    --header 'X-Frankie-CustomerID: {{your_customer_id}}'
    --data '{  
        "individual": {  
            "name": { "givenName": "John", "familyName": "Doe" },  
            "dateOfBirth": { "year": "1990", "month": "01", "day": "25" },  
            "..." : "..."  
        }  
    }'

​
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 beCOMPLETED. 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.
HTTP
    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.
JSON Request
    {  
      "status": "PASS",  
      "comment": {  
        "text": "Manually approved by compliance officer John Doe after reviewing supporting documents."  
      }  
    }

​
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