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 steps (e.g., organization data collection, ownership insights, etc.) to return a result. This is the central mechanism for fetching organization details, 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 organization already exists in your system.

​
1. Execute a workflow using organizationToken or organization registration details

If you have searched for a business and retrieved its organizationToken, you can execute a workflow using that token. Alternatively, if you already know the business’s registration number and type, you can execute a workflow directly with those details. This approach removes the need for a separate “create organization” step and, if an organization entity with the same registration number and type already exists in our system, we run the workflow against the existing entity—preventing the creation of duplicate entities. Use Cases:
  • Onboarding a new business for the first time.

​
2. Execute for an Existing Entity

If you have already created an organization and have their entityId, or have run a workflow and have the entityId of the organization, you can execute a workflow against them at any time. Use Cases:
  • Re-running a workflow to re-assess risks.
  • Running a workflow for an existing entity post onboarding.
  • Performing periodic or event-driven reviews.
1

1. Initiate the Workflow

You send a POST request to the /execute endpoint for a specific entity and workflow. This tells FrankieOne to initiate the workflow. The API response will have a status of 202 Accepted and contain the workflowExecutionId which can then be used to get the results of the workflow.
2

2. Retrieve the Workflow Result

You can retrieve the workflow result by making a GET request to the /executions/{workflowExecutionId} endpoint. The API response will have a status of 200 OK and contain the workflowResult object.

​
3. Re-evaluate an Existing Entity

If an entity has already been through a workflow and you need to update its compliance status, for example, after classifying AML hits or resolving duplicates, you should call the evaluate endpoint instead of executing the workflow again. The evaluate endpoint re-runs the decision and risk assessment steps using existing check results. It does not call external providers (e.g., CreditorWatch), which means:
  • No additional provider cost - external data fetches are skipped entirely.
  • Faster processing - only local computation steps are run.
Use Cases:
  • Updating the workflow result after classifying AML hits.
  • Re-assessing risk after resolving duplicate entities.
  • Recalculating the decision after a risk factor override.
When to use Execute instead: If the entity’s underlying data has changed and you need fresh provider data, or if existing check results have expired beyond the ageing window, use /execute.

​
Implementation Guide

​
Prerequisites

Before executing a workflow, ensure you have:
  • The organizationToken or registrationNumber and registrationType of the organization.
  • If the organization already exists in the system, the entityId for the organization.
  • The serviceName of the Service Profile they are being assessed against (e.g., DEFAULT).
  • The workflowName of the specific workflow you want to run (e.g., GLB-Organization-Profile).

​
Step 1: Initiate the Workflow

​
Request

Choose the endpoint that matches your execution pattern.
With Organization details:
Make a POST request to the endpoint, providing the organizationToken from the search response or registrationNumber, registrationType and country in the request body. 
curl --location 'https://api.uat.frankie.one/v2/organizations/workflows/GLB-Organization-Profile/execute' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "organization": {
        "details": {
            "registrationDetails": [
                {
                    "number": "61623506892",
                    "type": "ABN",
                    "country": "AUS"
                }
            ]
        }
        }
}'
You can pass a comment in the request body to provide additional context about the workflow execution. The comment will be added to the audit trail of the workflow execution. You can also pass serviceName in the request body to override the default configured service profile.
With EntityId:
This endpoint is used to execute a workflow for an existing entity. Make a POST request to the execute endpoint, including the entityId, serviceName, and workflowName in the path. 
curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "comment": {
        "text": "Invoking Profile workflow"
    }
}'
Evaluate for an Existing Entity:
If the entity has already been through a workflow execution and you need to re-assess its compliance status (e.g., after classifying AML hits), use the evaluate endpoint. 
curl --location --request POST 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/evaluate' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json' \
--data '{
    "comment": {
        "text": "Re-evaluating after AML hit classification"
    }
}'
The evaluate endpoint requires a prior completed workflow execution. If no prior execution exists, the API returns 400. If the entity’s underlying data has changed and existing check results have been invalidated, the evaluation may produce an incomplete assessment. In this case, use /execute to fetch fresh data.

​
Response

{
    "entityId": "01993733-cfd5-7594-9e90-ec3ad06dd490",
    "requestId": "01K4VK7KWN6HEA43AQ0F13JZPT",
    "serviceName": "DEFAULT",
    "serviceProfileId": "64ec50f2-5e69-4fee-8d97-7db77f2b71cd",
    "workflowExecutionId": "01K4VK7QDJG631AWFKWYVE85Z5"
}
KYB workflows are asynchronous. The API response will have a status of 202 Accepted and contain the workflowExecutionId which can then be used to get the results of the workflow. The workflow will continue to process in the background.

​
Step 2: Retrieve the Workflow Result

You can retrieve the workflow result by using the workflowExecutionId returned in the previous step.

​
Request

curl --location 'https://api.uat.frankie.one/v2/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/executions/{{workflowExecutionId}}' \
--header 'api_key: YOUR_API_KEY' \
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
--header 'Content-Type: application/json'
workflowResult.workflowExecutionState indicates the execution state of the workflow. If it is IN_PROGRESS, the workflow is still running. You can poll the endpoint again to check the status. When the workflow is completed, the workflowResult.workflowExecutionState will be COMPLETED. At this point, you can parse the workflowResult object to understand the outcome of every step. Response will also contain the complete organization object with all the information about the business.

​
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