> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Orchestration

> How verification checks are auto-created, executed, and reused across cases in the Zenoo CLM platform.

# Check Orchestration

The check framework automatically creates, executes, and tracks verification requirements for each entity in a case. Checks are the system's way of verifying facts about a person or company through external providers.

## How checks are created

When a case entity is created (either through the API or as part of case creation), the orchestration service automatically:

1. Reads the verification type configuration for the entity type and role
2. Filters by due diligence level (CDD vs EDD)
3. Creates the appropriate records based on execution method

```mermaid theme={null}
flowchart TD
    A[Entity added to case] --> B[Read Verification Type config]
    B --> C{Execution method?}
    C -->|API / Manual| D[Create Required Check]
    C -->|Document / FreeText / Dropdown| E[Create Document Requirement]
    C -->|Hybrid| F[Create Both with cross-links]
    D --> G{Auto-execute?}
    G -->|Yes| H[Execute via API adapter]
    G -->|No| I[Status: Pending]
    H --> J[Process result]
    J -->|Pass| K[Check Complete]
    J -->|Refer / Fail| L[Generate Alert]
```

## Check types and categories

| Category    | Check Types                                         | Execution  |
| ----------- | --------------------------------------------------- | ---------- |
| `Screening` | PEP Screening, Sanctions Screening, Adverse Media   | API        |
| `Identity`  | Identity Verification, Biometric Verification       | API        |
| `Company`   | Company Registry, Directors Verification, UBO Check | API        |
| `Financial` | Credit Check, Source of Wealth                      | API/Manual |
| `EDD`       | Enhanced Due Diligence checks (added when required) | Manual     |

## Execution modes

Checks execute in one of three modes depending on the provider configuration:

<Tabs>
  <Tab title="Individual">
    ### Individual mode

    One API call per check. Used for simple, single-purpose verifications.

    **Example:** Twilio phone verification -- one call verifies one phone number.

    ```mermaid theme={null}
    sequenceDiagram
        participant Z as Zenoo
        participant P as Provider
        Z->>P: executeCheck(check_1)
        P-->>Z: Result
        Z->>P: executeCheck(check_2)
        P-->>Z: Result
    ```
  </Tab>

  <Tab title="Category Batch">
    ### Category batch mode

    One API call returns results for multiple check types. Used for providers that screen across multiple categories simultaneously.

    **Example:** WorldCheck -- one call returns PEP, Sanctions, and Adverse Media results.

    ```mermaid theme={null}
    sequenceDiagram
        participant Z as Zenoo
        participant P as WorldCheck
        Z->>P: executeCategoryCheck([PEP, Sanctions, AdverseMedia])
        P-->>Z: Results for all 3 checks
    ```
  </Tab>

  <Tab title="Async (Awaiting Client)">
    ### Async mode

    The check initiates a client-side process (e.g., document upload, selfie capture). Results arrive via webhook when the client completes the action.

    **Example:** Zenoo Verify identity check -- generates a verification URL, client completes document capture, result arrives via callback.

    ```mermaid theme={null}
    sequenceDiagram
        participant Z as Zenoo
        participant P as Provider
        participant C as Client
        Z->>P: initiateCheck()
        P-->>Z: verification_url + token
        Z-->>C: Redirect to verification URL
        C->>P: Complete verification
        P->>Z: Webhook callback with results
    ```

    Checks in this mode have a configurable expiry. An hourly batch job marks expired `Awaiting Client` checks as `Failed`.
  </Tab>
</Tabs>

## Check status lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Pending
    Pending --> Queued : Auto-execute queued
    Pending --> In_Progress : Manual start
    Pending --> Waived : Analyst waives
    Queued --> In_Progress : Execution begins
    In_Progress --> Complete : Result received
    In_Progress --> Failed : Error or timeout
    In_Progress --> Awaiting_Document : Hybrid, needs upload
    In_Progress --> Awaiting_Client : Client interaction needed
    Awaiting_Client --> Complete : Client completes
    Awaiting_Client --> Failed : Expired
    Awaiting_Document --> Complete : Document received
    Complete --> [*]
    Failed --> Retry_Scheduled : Retry queued
    Retry_Scheduled --> In_Progress : Retry executes
    Failed --> [*]
    Waived --> [*]
```

| Status              | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `Pending`           | Created, awaiting execution or manual action          |
| `Queued`            | Scheduled for automatic execution                     |
| `In Progress`       | Currently executing against an external provider      |
| `Awaiting Document` | Hybrid check waiting for document upload              |
| `Awaiting Client`   | Waiting for client-side action (e.g., selfie capture) |
| `Complete`          | Execution finished with a result                      |
| `Failed`            | Execution error or timeout                            |
| `Waived`            | Manually waived by an analyst with documented reason  |
| `Cancelled`         | Cancelled (e.g., case closed before execution)        |
| `Reused`            | Valid check from another case reused                  |
| `Retry Scheduled`   | Failed check scheduled for automatic retry            |

## Check results

Every completed check produces one of three results:

| Result  | Meaning                        | Alert generated? |
| ------- | ------------------------------ | ---------------- |
| `Pass`  | Verification passed, no issues | No               |
| `Refer` | Potential issue, needs review  | Yes              |
| `Fail`  | Verification failed            | Yes              |

## Check reuse (Verify Once, Reference Many)

When a new case creates checks for an entity that has already been verified, the system evaluates existing checks for reuse:

1. Look up completed, passing checks for the same entity and check type
2. Verify the check has not expired (based on validity period)
3. If valid, create a `Reused` check referencing the original

This avoids redundant provider calls while maintaining full audit provenance.

| Check Category | Default Validity |
| -------------- | ---------------- |
| Identity       | 365 days         |
| Screening      | 90 days          |
| Company        | 180 days         |
| Financial      | 365 days         |
| EDD            | 180 days         |

## Alert generation

Checks that return `Refer` or `Fail` automatically generate alerts:

| Check Result           | Alert Category  | Alert Priority |
| ---------------------- | --------------- | -------------- |
| PEP screening match    | `PEP Match`     | High           |
| Sanctions match        | `Sanctions Hit` | Critical       |
| Adverse media hit      | `Adverse Media` | Medium         |
| Company dissolved      | `API Failure`   | High           |
| Name mismatch (\< 70%) | `Name Mismatch` | High/Medium    |
| Identity failure       | `Name Mismatch` | Medium         |

## Next steps

* [Alert Management](/guides/alert-management). How generated alerts are triaged and resolved.
* [Entity Lifecycle](/guides/entity-lifecycle). How entity roles drive check requirements.
* [Checks Data Model](/data-model/checks). Full field reference for check resources.