Executing Workflows

Overview of Individual KYC Workflows

Individual KYC Workflows are structured processes designed to verify the identity of individuals. These workflows encompass various checks, including AML (Anti-Money Laundering), IDV (Identity Verification), and Matchlist checks, ensuring compliance and accuracy. They are highly customizable, allowing organizations to tailor workflows to their specific requirements. This flexibility enables the creation and execution of workflows that address unique business needs while managing results effectively for individual entities.

How Workflows Are Set Up

Workflows are defined by several key attributes that determine their behavior and execution:

These attributes allow organizations to define workflows that align with their operational and compliance needs, ensuring flexibility and precision in execution.

Workflow Execution Process

This section provides a detailed guide on executing workflows, monitoring their progress, retrieving results, and managing exceptions. It ensures organizations can effectively implement and optimize their KYC processes while maintaining compliance and operational efficiency.

1. Get Executable Workflows

Retrieve a list of workflows that can be executed for a specific service profile. This is the first step in the workflow execution process.

$
GET /v2/workflows

1
{
2
"requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
3
    "workflows": [
4
    {
5
    "serviceName": "AML Screening",
6
    "workflowId": "workflow_12345", 
7
    "workflowName": "PEP & Sanctions",
8
    "type": "pep_media",
9
    "lifecyclePhase": "MONITORING", // The lifecycle phase of the customer in which this workflow would be executed
10
    "monitoringTypes": [    // The type of monitoring that this workflow is subscribed to.
11
        "AML"
12
    ]
13
    }
14
],
15
}

Make a note of the serviceName, workflowId, and workflowName for the workflow you want to execute.

2. Initiate Workflow Execution

Trigger the execution of the workflow for a specific individual entity. This step initiates the KYC checks and processes defined in the workflow.

$
POST v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute

A single workflow execution can contain multiple workflow steps. A successful execution will return a workflowExecutionId, which is crucial for tracking the execution status and results.

3. Monitor Execution Status

Monitor the status of the workflow execution to track its progress. This step is essential for understanding whether the workflow has completed successfully or if there are any issues.

$
GET v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions

1
{
2
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q85",
3
  "workflowExecutionState": "INPROGRESS"
4
}

4. Override Execution Status

In some cases, you may need to manually override the status of a workflow execution. This is useful for handling exceptions or applying manual decisions based on specific circumstances.

$
PATCH /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}

1
{
2
  "status": "PASS", // UNCHECKED, IN_PROGRESS, REVIEW, PASS, FAIL, COMPLETE, INCOMPLETE, NEEDS_APPROVAL, APPROVED, REJECTED, BLOCKED, CLEAR, URGENT, MONITOR
3
  "comment": {
4
    "text": "Update after speaking to customer over phone directly"
5
  }
6
}

The status field can be set to various values, including PASS, FAIL, IN_PROGRESS, and others, depending on the specific requirements of your workflow. The comment field allows you to provide additional context or notes regarding the status update.

5. Retrieve Execution Results

After the workflow execution is complete, retrieve the results to analyze the outcomes of the checks performed. This endpoint provides detailed information about the execution, including the status, risk assessment, and step outcomes.

$
GET v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/executions/{workflowExecutionId}

1
{
2
  "requestId": "REQ123456",
3
  "workflowResult": {
4
    "schemaVersion": 0,
5
    "workflowName": "AML Monitoring",
6
    "workflowExecutionId": "string",
7
    "workflowExecutionState": "COMPLETED",
8
    "status": "UNCHECKED",
9
    "statusOverrideAt": "2025-04-16T06:35:00.797Z",
10
    "statusOverrideRequestId": "REQ456789",
11
    "statusOverrideBy": "OPERATOR123",
12
    "riskAssessment": {...},
13
    "isManual": true,
14
    "steps": {...},
15
    "startedAt": "2025-04-16T06:35:00.797Z",
16
    "endedAt": "2025-04-16T06:35:00.797Z",
17
    "issues": [
18
      {...}
19
    ],
20
    "lifecyclePhase": "OTHER", //The lifecycle phase of the customer in which this workflow would be executed,
21
    "monitoringTypes": [
22
      "AML"
23
    ],
24
    "workflowId": "WORKFLOW123",
25
    "requestId": "REQ98765",
26
    "entityId": "ENTITY123",
27
    "entityType": "INDIVIDUAL",
28
    "serviceProfileId": "SERVICE_PROFILE_123",
29
    "endWorkflowId": "WORKFLOW_456",
30
    "endWorkflowName": "AML Monitoring",
31
    "workflowStepResults": [
32
      {...}
33
    ],
34
    "result": "UNCHECKED", //Outcome of this workflow execution.
35
    "errors": [
36
      {...}
37
    ],
38
    "notes": {...}
39
    },
40
    "createdAt": "2025-04-16T06:35:00.797Z",
41
    "updatedAt": "2025-04-16T06:35:00.797Z",
42
    "updatedBy": "OPERATOR123",
43
}

Managing Results

Once the workflow execution is complete, you can manage the results for the individual entity. This includes updating or invalidating results as necessary.

Get Process Results

Retrieve a comprehensive list of process results for a specific individual entity, including detailed information about each process and its outcomes.

$
GET /v2/individuals/{entityId}/results

1
{
2
    "requestId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
3
    "processResults": [
4
        {
5
            "processResultId": "pr-example-123",
6
            "entityId": "individual-456",
7
            "stepName": "IDV",
8
            "stepType": "DOCUMENT_VERIFICATION",
9
            "objectType": "IDENTITY_DOCUMENT",
10
            "objectId": "passport_123",
11
            "createdAt": "2025-04-17T01:00:00.000Z",
12
            "updatedAt": "2025-04-17T01:00:05.000Z",
13
            "result": "MATCH",
14
            "class": "KYC",
15
            "providerResult": {
16
                "name": "Veriff",
17
                "source": "Veriff - Document Check",
18
                "reference": "veriff-session-abc-123",
19
                "confidence": {
20
                    "normalized": 95
21
                }
22
            },
23
            "supplementaryData": {
24
                "type": "DOCUMENT",
25
                "matchData": {
26
                    "name": "John Doe",
27
                    "familyName": "Doe",
28
                    "givenName": "John",
29
                    "nationalId": {
30
                        "idNumber": "123456789",
31
                        "idType": "PASSPORT",
32
                        "issuingCountryCode": "AUS"
33
                    }
34
                }
35
            },
36
            "errors": [],
37
            "systemStatus": "VALID",
38
            "manualStatus": null
39
        }
40
    ]
41
}

Approve Manual KYC

Approve manual KYC (mKYC) for an individual to allow them to pass all KYC workflow steps without performing eKYC.

$
POST /v2/individuals/{entityId}/results/mkyc

1
{
2
  "approvedBy": "OPERATOR123",
3
  "approvedDocuments": [
4
    "3fa85f64-5717-4562-b3fc-2c963f66afa6" // Document ID
5
  ],
6
  "comment": {
7
    "text": "Update after speaking to customer over phone directly"
8
  }
9
}

Invalidate Manual KYC

Invalidate any manual KYC evidences of an individual to ensure that the KYC process is not compromised. This will force the entity to be verified by eKYC processes when KYC verification is next run.

$
POST /v2/individuals/{entityId}/results/mkyc/invalidate

1
{
2
  "comment": {
3
    "text": "Invalidated due to insufficient evidence."
4
  }
5
}

Update AML Results

Modify the status of AML process results for an individual entity to reflect manual decisions or updates. After reviewing the supplementaryData for AML screening match details, you can determine whether the individual being evaluated matches the entity identified during screening (true positive) or not (false positive).

To classify an AML screening hit as true positive, false positive, or unknown, update the manualStatus field of the process result. This field allows you to record manually determined statuses without altering the original result obtained during workflow execution.

$
PATCH /v2/individuals/{entityId}/results/aml

1
{
2
  "processResults": [ //
3
    "string" // The process results ID of the AML process
4
  ],
5
  "manualStatus": "TRUE_POSITIVE", //TRUE_POSITIVE, FALSE_POSITIVE, TRUE_POSITIVE_ACCEPT, TRUE_POSITIVE_REJECT, UNKNOWN, UNKNOWN_ACCEPT, UNKNOWN_REJECT
6
  "comment": {
7
    "text": "Update after speaking to customer over phone directly"
8
  }
9
}

1
{
2
  "processResults": [
3
    "string"
4
  ],
5
  "manualStatus": "TRUE_POSITIVE",
6
  "comment": {
7
    "text": "Update after speaking to customer over phone directly"
8
  }
9
}

1
{
2
  "processResults": [
3
    "string"
4
  ],
5
  "manualStatus": "FALSE_POSITIVE",
6
  "comment": {
7
    "text": "Update after speaking to customer over phone directly"
8
  }
9
}

Update IDV Results

Modify the status of IDV (Identity Verification) process results for an individual entity to reflect manual decisions or updates.

$
PATCH /v2/individuals/{entityId}/results/idv

1
{
2
  "processResults": [ //
3
    "string" // The process results ID of the IDV process
4
  ],
5
  "manualStatus": "CLEAR", // CLEAR, REJECTED
6
  "comment": {
7
    "text": "Update after speaking to customer over phone directly"
8
  }
9
}

Update Matchlist Results

Modify the status of Matchlist process results for an individual entity to reflect manual decisions or updates.

$
PATCH /v2/individuals/{entityId}/results/matchlist

1
{
2
  "processResults": [ //
3
    "string" // The process results ID of the Matchlist process
4
  ],
5
  "manualStatus": "TRUE_POSITIVE", //TRUE_POSITIVE, FALSE_POSITIVE, TRUE_POSITIVE_ACCEPT, TRUE_POSITIVE_REJECT, UNKNOWN, UNKNOWN_ACCEPT, UNKNOWN_REJECT
6
  "comment": {
7
    "text": "Update after speaking to customer over phone directly"
8
  }
9
}

Update Duplicate Results

Modify the status of Duplicate process results for an individual entity to reflect manual decisions or updates.

$
PATCH /v2/individuals/{entityId}/results/duplicate

1
{
2
  "processResults": [ //
3
    "string" // The process results ID of the Duplicate process
4
  ],
5
  "manualStatus": "TRUE_POSITIVE", //FALSE_POSITIVE, TRUE_POSITIVE_ACCEPT, TRUE_POSITIVE_REJECT
6
  "comment": {
7
    "text": "Update after speaking to customer over phone directly"
8
  }
9
}