> ## Documentation Index > Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt > Use this file to discover all available pages before exploring further. # Executing a Workflow > A step-by-step guide to executing workflows and interpreting the results. ## 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. 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. 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 risk and workflow 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. ```bash Request - Execute Workflow with registration details theme={null} 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" } ] } } }' ``` ```bash Request - Execute Workflow with organizationToken theme={null} curl --location 'https://api.uat.frankie.one/v2/organizations/workflows/organization_profile/execute' \ --header 'api_key: YOUR_API_KEY' \ --header 'X-Frankie-CustomerId: YOUR_CUSTOMER_ID' \ --header 'Content-Type: application/json' \ --data '{ "organizationToken": "eyJ2ZXIiOiIxLjAiLCJ0cyI6IjIwMjUtMDgtMDdUMDY6NTk6NTQuNDAzMzcxNDZaIiwib24iOlt7InJuIjoiNjE2MjM1MDY4OTIiLCJyYSI6IkFCTiJ9LHsicm4iOiI2MjM1MDY4OTIiLCJyYSI6IkFDTiJ9XSwicHJvdiI6ImNyZWRpdG9yd2F0Y2giLCJjbyI6IkFVUyJ9", "serviceName": "DEFAULT" }' ``` 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. #### Request Body Fields | Field | Type | Required | Description | | -------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `organizationToken` | `string` | Conditional | Token returned by a business lookup. Use this **or** `organization`, not both. | | `organization` | `object` | Conditional | Organization registration details. Use this **or** `organizationToken`, not both. | | `serviceName` | `string` | No | Override the default service profile. | | `comment` | `object` | No | Audit trail comment. Pass `{ "text": "..." }`. | | `executionVariables` | `object` | No | Runtime variables consumed by workflow tasks. Keys and types are defined per workflow. See [Execution Variables](#execution-variables) below. | #### Execution Variables `executionVariables` is a key-value object that passes runtime inputs into a workflow's tasks without changing the entity's persistent data. The variables a workflow accepts are defined by that workflow's configuration. Today the only workflow that uses `executionVariables` is the [Trust Analyzer](/docs/kyb/trust-analyzer) (`GLB-Trust-Analysis`), which takes the `documentId` of an uploaded trust deed. ```json Example - executionVariables for Trust Analysis theme={null} { "executionVariables": { "documentId": "92de15f6-5717-4562-b3fc-2c963f6665a7" } } ``` See the [Trust Analyzer](/docs/kyb/trust-analyzer) guide for the full flow. ##### 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. ```bash Request - Execute Workflow with entityId theme={null} 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 risk and workflow status (e.g., after classifying AML hits), use the `evaluate` endpoint. ```bash Request - Evaluate Workflow with entityId theme={null} 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 ```json Response - Execute or Evaluate Workflow with entityId theme={null} { "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 ```bash Request - Retrieve Workflow Result theme={null} 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](/docs/kyb/interpreting-workflows-v2)**. *** ## Additional Resources * [FrankieOne API Reference](/docs/reference/whats-new) * [FrankieOne Support](/docs/contacting-developer-support)