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

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., KYB).
• The workflowName of the specific workflow you want to run (e.g., AUS-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.

1
curl --location 'https://api.uat.frankie.one/v2.1/organizations/workflows/AUS-Organization-Profile/execute' \
2
--header 'api_key: YOUR_API_KEY' \
3
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
4
--header 'Content-Type: application/json' \
5
--data '{
6
    "organization": {
7
        "details": {
8
            "registrationDetails": [
9
                {
10
                    "number": "61623506892",
11
                    "type": "ABN",
12
                    "country": "AUS"
13
                }
14
            ]
15
        }
16
        }
17
}'

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.

1
curl --location 'https://api.uat.frankie.one/v2.1/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute' \
2
--header 'api_key: YOUR_API_KEY' \
3
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
4
--header 'Content-Type: application/json' \
5
--data '{
6
    "comment": {
7
        "text": "Invoking Profile workflow"
8
    }
9
}'

Response

1
{
2
    "entityId": "01993733-cfd5-7594-9e90-ec3ad06dd490",
3
    "requestId": "01K4VK7KWN6HEA43AQ0F13JZPT",
4
    "serviceName": "KYB",
5
    "serviceProfileId": "64ec50f2-5e69-4fee-8d97-7db77f2b71cd",
6
    "workflowExecutionId": "01K4VK7QDJG631AWFKWYVE85Z5"
7
}

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

1
curl --location 'https://api.uat.frankie.one/v2.1/organizations/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/executions/{{workflowExecutionId}}' \
2
--header 'api_key: YOUR_API_KEY' \
3
--header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \
4
--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

• FrankieOne API Reference
• FrankieOne Support