Interpreting Workflows

Understanding the Workflow Response

After executing a workflow, the API returns a comprehensive workflowResult object. This object is the key to understanding the outcome of every check performed. This guide provides a structured, top-down walkthrough of how to parse this response, explaining each key object from the final verdict down to the granular evidence.

View Full API Response Example

The examples in this guide refer to the following API response for workflow execution 01JZHEX5FQA4DJB0MMJFZR26JS. Click to expand and see the full structure

    {  
        "individual": {  
            "entityId": "99f16410-2613-4181-8cf1-048625900013",  
            "name": { "displayName": "MARY TESTFOURTEEN", "...": "..." },  
            "...": "..."  
        },  
        "requestId": "01JZHEX0WX2QEM6EY139D5NNP1",  
        "workflowResult": {  
            "workflowExecutionId": "01JZHEX5FQA4DJB0MMJFZR26JS",  
            "workflowExecutionState": "COMPLETED",  
            "status": "PASS",  
            "result": "PASS",  
            "riskAssessment": {  
                "riskLevel": "LOW",  
                "riskScore": 12,  
                "riskFactors": [ { "factor": "entity_type", "value": "INDIVIDUAL", "score": 2 }, { "factor": "entity_age", "value": "62", "score": 10 } ]  
            },  
            "steps": {  
                "passed": [ "START", "MATCHLIST", "KYC", "AML", "DECISION", "FINISH" ],  
                "failed": [ "IDV" ],  
                "order": [ "START", "MATCHLIST", "KYC", "IDV", "AML", "TOGGLE_MONITORING", "DECISION", "FINISH" ],  
                "...": "..."  
            },  
            "issues": [],  
            "workflowStepResults": [  
                {  
                    "stepName": "KYC",  
                    "result": "MATCH",  
                    "processResults": [  
                        {  
                            "processResultId": "01JZ4H0P59KGQR9DZCWZ6JQRY0",  
                            "class": "KYC",  
                            "objectType": "NAME",  
                            "result": "MATCH",  
                            "state": "COMPLETED",  
                            "systemStatus": "VALID",  
                            "providerResult": {  
                                "name": "con_testbed-docs",  
                                "source": "au-govid1-pp"  
                            },  
                            "supplementaryData": {  
                                "type": "KYC_NAME",  
                                "matchStrengths": {  
                                    "fullName": 75,  
                                    "familyName": 75,  
                                    "givenName": 75  
                                }  
                            }  
                        }  
                    ],  
                    "summary": {  
                        "matchedRules": [  
                            {  
                                "ruleName": "gov_id_only",  
                                "isVerified": true,  
                                "matchDetails": [  
                                    {  
                                        "provider": "con_testbed-docs",  
                                        "source": "au-govid1-pp",  
                                        "attributesMatched": [ "dateOfBirth", "govId", "name" ]  
                                    }  
                                ]  
                            }  
                        ]  
                    },  
                    "...": "..."  
                }  
            ]  
        }  
    }

Part 1: The Overall Outcome (The Final Verdict)

Start by examining the top-level fields of the workflowResult object. These provide the final, authoritative outcome of the entire workflow execution.

Field Name	Importance	Description
`status`	‼️	This is the most important field. It represents the conclusive recommendation and accounts for any manual overrides. Base your primary business logic on this value.
`workflowExecutionState`	‼️	This confirms the workflow’s technical status. It `must beCOMPLETED` for the `status` to be considered final.
`result`	⚠️	This field holds the original, automated outcome of the workflow before any manual changes. It is useful for auditing.
`issues`	⚠️	An array of problems that may require manual review. If the `status` is `REVIEW`, this array will contain the specific reasons why.

Workflow Execution States (`workflowExecutionState`)

This field tells you if the workflow ran to completion.

State	Description
`COMPLETED`	The workflow executed successfully from start to finish.
`IN_PROGRESS`	The workflow is still running.
`ERROR`	The workflow encountered an unrecoverable error and could not finish.
`TIMEOUT`	The workflow exceeded its maximum execution time.
`CANCELED`	The workflow was manually canceled before completion.
`TERMINATED`	The workflow was terminated by the system before completion.

When Each Execution State Occurs

COMPLETED

The workflow ran to completion. This is the expected state for most synchronous workflows.

Next step: Check workflowResult.status for the verification outcome (PASS, FAIL, REVIEW, etc.)

IN_PROGRESS

The workflow is still executing and has not yet reached a terminal state. This occurs when:

Scenario	Example
Workflow includes asynchronous steps	IDV document verification, biometric/liveness checks
External provider is processing	Third-party identity verification pending
Waiting for user action	Document upload or selfie capture in progress

Handling IN_PROGRESS responses:

Configure webhooks (recommended) - Listen for completion events:
- RESULTS_RETRIEVED - Verification results are ready
- FF_EXTERNAL_IDV_CHECK_COMPLETED - IDV/biometric submission complete
Poll for results - Call GET /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName} to retrieve updated results
Use the retrieve endpoint - Call /retrieve/{requestID} with the requestID from the original response

Note: Biometric checks are asynchronous and can take up to 5 minutes to complete. Do not treat IN_PROGRESS
as a failure.

ERROR

An unrecoverable error occurred during workflow execution. Common causes:

Internal system error
Invalid workflow configuration
Data source connector failure

Recommended action: Log the workflowExecutionId and retry the request. If persistent, contact
support@frankieone.com.

TIMEOUT

The workflow exceeded the maximum allowed execution time. Common causes:

External data source unavailable or slow
Network connectivity issues
High system load

Recommended action: Retry with exponential backoff. Check FrankieOne Status for service availability.

CANCELED

The workflow was manually canceled before completion. This can occur when:

The request was explicitly canceled via API
A dependent process was terminated

TERMINATED

The workflow was forcefully stopped by the system. This may indicate:

System-level intervention
Resource limits exceeded
Security policy triggered

Recommended action: Contact help@frankieone.com with the workflowExecutionId to investigate.

Workflow Statuses (`status` and `result`)

This is the final recommendation of the workflow.

Status	Description
`PASS`	The entity successfully met the workflow’s criteria.
`FAIL`	The entity did not meet the workflow’s criteria.
`REVIEW`	The workflow produced results that require manual review.
`CLEAR`	Often used for monitoring, indicates no negative information was found.
`HIT`	Often used for monitoring, indicates negative information (e.g., a watchlist match) was found.
`URGENT`	A critical issue was found (e.g., a sanctions match) that requires immediate attention.
`COMPLETE` / `INCOMPLETE`	The workflow finished, but a pass/fail determination was not applicable.

Detecting Manual Overrides

It’s crucial to know if a workflow’s result was changed by a person. When an operator manually changes the status (e.g., from FAIL to PASS), the following fields are populated:

statusOverrideRequestId: The unique ID of the override request.
statusOverrideBy: The user who performed the override.
statusOverrideAt: The timestamp of the override.

To detect an override, check ifstatusOverrideRequestId exists and is not empty.

Part 2: The Step-by-Step Breakdown (`workflowStepResults`)

The workflowStepResults array is a log of each individual check, explaining how the overall status was reached. Each object in this array corresponds to a step configured in your workflow (e.g., KYC, AML, IDV).

Field Name	Description
`stepName`	The name of the step (e.g., `KYC`, `AML`).
`result`	The outcome of this specific step. See the table below for all possible values.
`summary`	A concise, human-readable summary of the step’s outcome. For a KYC step, this includes which matching rules were met.
`processResults`	An array of Process Result Objects (PROs) providing the granular evidence for this step’s result.
`risk`	The risk assessment specific to this step, including the score it contributed to the overall risk.

Workflow Step Results (`result`)

Result	Applicable Steps	Description
MATCH / NO_MATCH / PARTIAL	KYC, IDV, VISA	The step produced a successful, unsuccessful, or partially successful match against data sources.
CLEAR / HIT	AML, MATCHLIST, DUPLICATE	The step checked against a negative list (e.g., AML watchlist) and found no matches (CLEAR) or found a match (HIT).
PASS / FAIL	DECISION, Manual KYC	The step completed and met (PASS) or did not meet (FAIL) its required binary criteria.
COMPLETE / INCOMPLETE	START, FINISH, RISK	The step finished, but a pass/fail scenario was not applicable.
SKIPPED	Any Step	The step was skipped because it was not required to run.
MISSING_DATA	Any Step	The step could not run because it requires additional data.
ERROR	Any Step	The step encountered an unrecoverable technical error.

Part 3: The Granular Evidence (`processResults`)

For the deepest level of detail, look inside a workflowStepResult at its processResults array. A Process Result Object (PRO) is the raw evidence from a single check against a single data source.

Field Name	Description
`processResultId`	A unique identifier for this specific piece of evidence.
`class`	The high-level category of the check. See the table below for details.
`objectType`	The specific data element that was checked (e.g., `NAME`, `ADDRESS`, `DOCUMENT`).
`result`	The outcome of this specific check (e.g., `MATCH`, `HIT`, `CLEAR`).
`providerResult`	An object containing details from the downstream data provider, including the `source` of the data.
`systemStatus`	The lifecycle status of this PRO (e.g., `VALID`, `STALE`, `MARKED_INVALID`). A `STALE` status means the underlying entity data has changed since this check was performed.
`manualStatus`	If an operator has manually reviewed this specific PRO, their conclusion (e.g., `TRUE_POSITIVE`, `FALSE_POSITIVE`) is recorded here.
`supplementaryData`	A rich, context-specific object containing detailed metrics, like match scores or extracted OCR data.

Process Result Classes (`class`)

Class	Description
`KYC`	An electronic Know Your Customer check against a data source.
`IDV`	An Identity Verification check, typically involving biometrics and document analysis.
`AML`	An Anti-Money Laundering screening against watchlists, sanctions, and PEP lists.
`MATCHLIST`	A check against a custom internal or shared blocklist/allowlist.
`DUPLICATE`	A check to see if the entity is a duplicate of an existing entity.
`FRAUD`	A fraud check, often related to device, IP, or behavioral signals.

Best Practices for Integration

CheckworkflowExecutionState first: Always confirm the workflow is COMPLETED before trusting the status.
Automate based onstatus: Use the top-level status field for your primary business logic (e.g., approve account, flag for review).
Debug withworkflowStepResults: When you get an unexpected FAIL or REVIEW, loop through the workflowStepResults to find which stepName has a non-passing result. The summary and processResults within that step will tell you why.
Log theworkflowExecutionId: This ID is your key for auditing, support queries, and correlating results.

Synchronous vs Asynchronous Workflows

Workflow behavior depends on the types of checks configured in your workflow.

Synchronous Workflows

Workflows containing only synchronous steps return COMPLETED immediately with the final result. Synchronous step types:

KYC data source checks (government databases, credit bureaus)
AML/PEP/Sanctions screening
Watchlist checks
Duplicate detection

Example response:

{                                                                                                                   
  "workflowResult": {                                                                                               
    "workflowExecutionState": "COMPLETED",                                                                          
    "workflowExecutionId": "wfe_abc123",                                                                            
    "status": "PASS",                                                                                               
    "result": "PASS"                                                                                                
  }                                                                                                                 
}                                                                                                                   
                                                                                                                    
Asynchronous Workflows                                                                                              
                                                                                                                    
Workflows containing asynchronous steps may return IN_PROGRESS initially.                                           
                                                                                                                    
Asynchronous step types:                                                                                            
- IDV (Identity Document Verification)                                                                              
- Biometric verification / Liveness detection                                                                       
- Manual review steps                                                                                               
- Some third-party provider integrations                                                                            
                                                                                                                    
Example response:                                                                                                   
{                                                                                                                   
  "workflowResult": {                                                                                               
    "workflowExecutionState": "IN_PROGRESS",                                                                        
    "workflowExecutionId": "wfe_xyz789",                                                                            
    "status": null                                                                                                  
  }                                                                                                                 
}                                                                                                                   
                                                                                                                    
Determining Your Workflow Type                                                                                      
                                                                                                                    
To check if your workflow includes asynchronous steps:                                                              
1. Call GET /v2/workflows to list your configured workflows                                                         
2. Review the step configuration with your Customer Success Manager                                                 
3. Test in sandbox environment to observe response behavior                                                         
                                                                

​Understanding the Workflow Response

​Part 1: The Overall Outcome (The Final Verdict)

​Workflow Execution States (workflowExecutionState)

​When Each Execution State Occurs

​COMPLETED

​IN_PROGRESS

​ERROR

​TIMEOUT

​CANCELED

​TERMINATED

​Workflow Statuses (status and result)

​Detecting Manual Overrides

​Part 2: The Step-by-Step Breakdown (workflowStepResults)

​Workflow Step Results (result)

​Part 3: The Granular Evidence (processResults)

​Process Result Classes (class)

​Best Practices for Integration

​Synchronous vs Asynchronous Workflows

​Synchronous Workflows