KYBImplementation Guide

Interpreting Workflows

A developer's guide to parsing the workflowResult object, from the overall status down to the granular details of each step.

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

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

1{
2    "organization": {
3        "entityId": "99f16410-2613-4181-8cf1-048625900013",
4        "details": { "name": "Frankie One", "registrationDetails": [ ... ] },
5        "...": "..."
6    },
7    "requestId": "01JZHEX0WX2QEM6EY139D5NNP1",
8    "workflowResult": {
9        "createdAt": "2025-09-12T01:09:31.804846Z",
10        "endedAt": "2025-09-12T01:09:36.912755Z",
11        "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
12        "entityType": "ORGANIZATION",
13        "issues": [],
14        "lifecyclePhase": "ONBOARDING",
15        "monitoringTypes": [],
16        "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
17        "result": "COMPLETE",
18        "riskAssessment": {
19            "createdAt": "2025-09-12T01:09:31.857427Z",
20            "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
21            "riskAssessmentId": "56adfe52-cdcb-414e-9819-a541953a5858",
22            "riskFactors": [
23                {
24                    "createdAt": "2025-09-11T04:20:59.47008Z",
25                    "description": "Organization Type",
26                    "factor": "organization_type",
27                    "riskFactorId": "be53f30a-d1fe-4264-aec7-c798444c391d",
28                    "score": 30,
29                    "status": "VALID",
30                    "updatedAt": "2025-09-11T04:20:59.47008Z",
31                    "updatedRequestId": "01K4VG2EVV6YJEQFEWZNR4RRY7"
32                }
33            ],
34            "riskScore": 30,
35            "serviceProfileId": "081f345f-0919-4a60-8f23-e84cdd8bcf11",
36            "updatedAt": "2025-09-12T01:09:37.095762Z",
37            "updatedRequestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
38            "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX",
39            "workflowId": "62758fca-6e95-424e-85ae-2d246bb45d92",
40            "workflowRiskLevel": "LOW",
41            "workflowRiskScore": 30
42        },
43        "schemaVersion": 2,
44        "serviceProfileId": "081f345f-0919-4a60-8f23-e84cdd8bcf11",
45        "startedAt": "2025-09-12T01:09:31.804846Z",
46        "status": "COMPLETE",
47        "statusOverrideAt": "0001-01-01T00:00:00Z",
48        "statusOverrideBy": "",
49        "statusOverrideRequestId": "",
50        "steps": {
51            "failed": [],
52            "incomplete": [],
53            "notApplicable": [],
54            "order": [
55                "START",
56                "ORGANIZATION_DATA_FETCH",
57                "ORGANIZATIONPERSIST",
58                "DECISION",
59                "FINISH"
60            ],
61            "passed": [
62                "START",
63                "ORGANIZATION_DATA_FETCH",
64                "ORGANIZATIONPERSIST",
65                "DECISION",
66                "FINISH"
67            ]
68        },
69        "updatedAt": "2025-09-12T01:09:37.258784Z",
70        "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX",
71        "workflowExecutionState": "COMPLETED",
72        "workflowId": "62758fca-6e95-424e-85ae-2d246bb45d92",
73        "workflowName": "AUS-Organization-Ownership",
74        "workflowStepResults": [
75            {
76                "createdAt": "2025-09-12T01:09:36.891039Z",
77                "endedAt": "2025-09-12T01:09:36.912755Z",
78                "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
79                "objectType": "ORGANIZATION",
80                "processResults": [],
81                "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
82                "result": "COMPLETE",
83                "risk": {
84                    "contributedScore": 0,
85                    "level": "LOW",
86                    "overallScore": 30
87                },
88                "schemaVersion": 2,
89                "startedAt": "2025-09-12T01:09:36.884705Z",
90                "stepName": "FINISH",
91                "stepResultId": "01K4XQGZZV1HK6RRYRPEK9HH1X",
92                "summary": {
93                    "stepName": "FINISH",
94                    "workflowContextId": "2e7b0cc9-0545-4399-a89a-303c63243fde"
95                },
96                "updatedAt": "2025-09-12T01:09:37.233237Z",
97                "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
98            },
99            {
100                "createdAt": "2025-09-12T01:09:36.560444Z",
101                "endedAt": "2025-09-12T01:09:36.584254Z",
102                "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
103                "objectType": "ORGANIZATION",
104                "processResults": [],
105                "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
106                "result": "COMPLETE",
107                "schemaVersion": 2,
108                "startedAt": "2025-09-12T01:09:36.54998Z",
109                "stepName": "DECISION",
110                "stepResultId": "01K4XQGZNGJC9KSH3BJ5GWHDZ2",
111                "summary": {
112                    "stepName": "DECISION",
113                    "workflowExecutionResult": "COMPLETE"
114                },
115                "updatedAt": "2025-09-12T01:09:36.732859Z",
116                "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
117            },
118            {
119                "createdAt": "2025-09-12T01:09:34.533563Z",
120                "endedAt": "2025-09-12T01:09:36.125729Z",
121                "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
122                "objectType": "ORGANIZATION",
123                "processResults": [],
124                "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
125                "result": "COMPLETE",
126                "risk": {
127                    "contributedScore": 30,
128                    "level": "LOW",
129                    "overallScore": 30
130                },
131                "schemaVersion": 2,
132                "startedAt": "2025-09-12T01:09:34.527693Z",
133                "stepName": "ORGANIZATIONPERSIST",
134                "stepResultId": "01K4XQGXP5505XGKTZKJWQZAPQ",
135                "summary": {
136                    "stepName": "ORGANIZATION_PERSIST"
137                },
138                "updatedAt": "2025-09-12T01:09:36.381606Z",
139                "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
140            },
141            {
142                "createdAt": "2025-09-12T01:09:32.467337Z",
143                "endedAt": "2025-09-12T01:09:33.724934Z",
144                "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
145                "objectType": "ORGANIZATION",
146                "processResults": [
147                    {
148                        "class": "ORGANIZATION_PROFILE",
149                        "createdAt": "2025-09-11T04:20:56.176612Z",
150                        "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
151                        "objectType": "ORGANIZATION",
152                        "processResultId": "01K4VG2K7GQ0FPQE1FSNRPWM53",
153                        "providerResult": {
154                            "name": "ABR",
155                            "source": "ABR",
156                            "sourceNormalized": "ABR"
157                        },
158                        "requestId": "01K4VG2EVV6YJEQFEWZNR4RRY7",
159                        "result": "CREATED",
160                        "schemaVersion": 2,
161                        "state": "COMPLETED",
162                        "stepName": "ORGANIZATION_DATA_FETCH",
163                        "stepType": "ORGANIZATION_PROFILE",
164                        "supplementaryData": {
165                            "organization": {
166                                ...
167                            },
168                            "type": "KYB_ORGANIZATION"
169                        },
170                        "systemStatus": "VALID",
171                        "updatedAt": "2025-09-11T04:20:56.176612Z"
172                    },
173                    {
174                        "class": "ORGANIZATION_OWNERSHIP",
175                        "createdAt": "2025-09-12T01:09:33.705433Z",
176                        "entityId": "01993700-edfb-766f-98d2-9fe470d78825",
177                        "objectType": "ORGANIZATION",
178                        "processResultId": "01K4XQGWW9DN9H4YZF6XKK7T44",
179                        "providerResult": {
180                            "name": "CREDITOR_WATCH",
181                            "reference": "2f3b7f30-ca8d-11eb-816f-0242ac11001b",
182                            "source": "ASIC",
183                            "sourceNormalized": "ASIC"
184                        },
185                        "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
186                        "result": "CREATED",
187                        "schemaVersion": 2,
188                        "state": "COMPLETED",
189                        "stepName": "ORGANIZATION_DATA_FETCH",
190                        "stepType": "ORGANIZATION_OWNERSHIP",
191                        "supplementaryData": {
192                            "organization": {
193                                ...
194                            },
195                            "type": "KYB_ORGANIZATION"
196                        },
197                        "systemStatus": "VALID",
198                        "updatedAt": "2025-09-12T01:09:33.705433Z"
199                    }
200                ],
201                "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
202                "result": "COMPLETE",
203                "schemaVersion": 2,
204                "startedAt": "2025-09-12T01:09:32.457875Z",
205                "stepName": "ORGANIZATION_DATA_FETCH",
206                "stepResultId": "01K4XQGVNKJBAKMCSQ3RFE2358",
207                "summary": {
208                    "provider": "CREDITORWATCH",
209                    "stepName": "ORGANIZATION_DATA_FETCH"
210                },
211                "updatedAt": "2025-09-12T01:09:33.850884Z",
212                "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
213            },
214            {
215                "createdAt": "2025-09-12T01:09:31.937737Z",
216                "endedAt": "2025-09-12T01:09:31.979769Z",
217                "objectId": "01993700-edfb-766f-98d2-9fe470d78825",
218                "objectType": "ORGANIZATION",
219                "processResults": [],
220                "requestId": "01K4XQGPNYVR9PDCZ5ESW264V3",
221                "result": "COMPLETE",
222                "risk": {
223                    "contributedScore": 30,
224                    "level": "LOW",
225                    "overallScore": 30
226                },
227                "schemaVersion": 2,
228                "startedAt": "2025-09-12T01:09:31.927456Z",
229                "stepName": "START",
230                "stepResultId": "01K4XQGV515Y9RMX9G9T85AGR3",
231                "summary": {
232                    "stepName": "START",
233                    "workflowContextId": "2e7b0cc9-0545-4399-a89a-303c63243fde",
234                    "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
235                },
236                "updatedAt": "2025-09-12T01:09:32.197792Z",
237                "workflowExecutionId": "01K4XQGV10NY0Q3SE0F73H9TJX"
238            }
239        ]
240    }
241}

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 NameImportanceDescription
status‼️It represents the conclusive recommendation and accounts for any manual overrides.
workflowExecutionState‼️This confirms the workflow’s technical status. It must be COMPLETED for the status to be considered final and to review the organization object.
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.

StateDescription
COMPLETEDThe workflow executed successfully from start to finish.
IN_PROGRESSThe workflow is still running.
ERRORThe workflow encountered an unrecoverable error and could not finish.
TIMEOUTThe workflow exceeded its maximum execution time.
CANCELEDThe workflow was manually canceled before completion.
TERMINATEDThe workflow was terminated by the system before completion.

Workflow Statuses (status and result)

This is the final recommendation of the workflow.

StatusDescription
PASSThe entity successfully met the workflow’s criteria.
FAILThe entity did not meet the workflow’s criteria.
REVIEWThe workflow produced results that require manual review.
CLEAROften used for monitoring, indicates no negative information was found.
HITOften used for monitoring, indicates negative information (e.g., a watchlist match) was found.
URGENTA critical issue was found (e.g., a sanctions match) that requires immediate attention.
COMPLETE / INCOMPLETEThe 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 if statusOverrideRequestId exists and is not empty.

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

The workflowStepResults array is a log of each step in the workflow, 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 NameDescription
stepNameThe name of the step (e.g., ORGANIZATION_DATA_FETCH, AML).
resultThe outcome of this specific step. See the table below for all possible values.
summaryA concise, human-readable summary of the step’s outcome.
processResultsAn array of Process Result Objects (PROs) providing the granular evidence for this step’s result.
riskThe risk assessment specific to this step, including the score it contributed to the overall risk.

Workflow Step Results (result)

ResultDescription
PARTIALThe step produced a successful, unsuccessful, or partially successful match against data sources.
CLEAR / HITIndicates no negative information found (CLEAR) or negative information found (HIT), e.g., a watchlist match.
PASS / FAILThe step completed and met (PASS) or did not meet (FAIL) its required criteria.
COMPLETE / INCOMPLETEThe step finished, but a pass/fail scenario was not applicable.
SKIPPEDThe step was skipped because it was not required to run.
MISSING_DATAThe step could not run because it requires additional data.
ERRORThe 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 NameDescription
processResultIdA unique identifier for this specific piece of evidence.
classThe high-level category of the step. See the table below for details.
objectTypeThe specific data element that was checked.
resultThe outcome of this specific step (e.g., MATCH, HIT, CLEAR).
providerResultAn object containing details from the downstream data provider, including the source of the data.
systemStatusThe 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.
manualStatusIf an operator has manually reviewed this specific PRO, their conclusion (e.g., TRUE_POSITIVE, FALSE_POSITIVE) is recorded here.
supplementaryDataA rich, context-specific object containing detailed metrics, like AML hits or extracted organization data.

Process Result Classes (class)

ClassDescription
ORGANIZATION_OWNERSHIPOrganization ownership data fetched from a data source.
ORGANIZATION_PROFILEOrganization profile data fetched from a data source.
AMLAn Anti-Money Laundering screening against watchlists, sanctions, and PEP lists.

Best Practices for Integration

  • Check workflowExecutionState first: Always confirm the workflow is COMPLETED before trusting the status and the returned organization object.
  • Debug with workflowStepResults: 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 the workflowExecutionId: This ID is your key for auditing, support queries, and correlating results.

References

For more details on specific workflowResult objects, please refer to our Features section.