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

# Architecture & Data Flow

> Understand how Zenoo orchestrates verification checks across providers and delivers unified compliance reports.

# Architecture & Data Flow

## Overview

Zenoo is a verification orchestration hub. You submit entity data to a single API endpoint. Zenoo routes checks to the appropriate providers (screening databases, company registries, document verification, and others), normalizes the results into a unified format, evaluates risk, and returns a structured compliance report.

One integration point. Multiple providers. Consistent results.

<Info>
  Your system communicates exclusively with Zenoo. Zenoo handles all provider and Salesforce interactions. You never need to integrate directly with screening databases, company registries, or document verification providers.
</Info>

## System Architecture

```mermaid theme={null}
flowchart LR
    A[Your System] -->|REST API| B[Zenoo Gateway]
    B -->|Checks| C[Providers]
    C -->|Results| B
    B -->|Enrichment| D[Salesforce Case Management]
    D -->|Enhanced Data| B
    B -->|Results| A
```

| Component         | Role                                                                                                        |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| **Your System**   | Submits entity data, receives compliance results                                                            |
| **Zenoo Gateway** | Orchestration hub -- routes checks, normalizes results, serves API                                          |
| **Providers**     | Screening databases, company registries, document verification, biometric liveness, phone verification      |
| **Salesforce**    | Back-end enrichment -- case management, risk scoring, AI research, UBO discovery, alert triage, audit trail |

## Processing Pipeline

When you submit entity data, Zenoo executes these stages:

<Steps>
  <Step title="Data ingestion">
    Your payload is validated and a case is created. If the `external_reference` already exists, the existing case is returned instead of creating a duplicate.
  </Step>

  <Step title="Screening">
    The entity and any associated individuals (directors, UBOs) are screened against WorldCheck databases for PEP status, sanctions matches, adverse media, and watchlist entries.
  </Step>

  <Step title="Registry verification">
    For companies, Zenoo queries official company registries to verify legal name, registration number, company status, registered address, directors, and shareholders.
  </Step>

  <Step title="Document verification">
    For Person Verification flows requiring user interaction, the individual captures identity documents and a selfie. Zenoo runs OCR, tamper detection, and biometric liveness checks.
  </Step>

  <Step title="Risk model evaluation">
    All check results feed into a risk scoring model that evaluates entity risk, geographic risk, industry risk, and screening risk. The output is a risk tier (Low, Medium, High) and a numeric score.
  </Step>

  <Step title="Alert generation">
    If screening returns hits, data mismatches are detected, or risk thresholds are exceeded, alerts are created for compliance review.
  </Step>

  <Step title="UBO discovery">
    For company verifications, beneficial owners are identified from registry data and screened individually.
  </Step>

  <Step title="AI research (optional)">
    Automated research on the entity using public data sources, producing a structured summary of background, industry presence, and risk indicators.
  </Step>
</Steps>

### Processing Timeline

| Stage                                      | Typical Duration        |
| ------------------------------------------ | ----------------------- |
| API gateway routing                        | \< 1 second             |
| WorldCheck screening                       | 3-10 seconds            |
| Company registry lookup                    | 5-15 seconds            |
| Document verification (after user submits) | 10-30 seconds           |
| Risk model evaluation                      | 1-5 seconds             |
| Alert generation                           | \< 1 second             |
| UBO discovery                              | Part of registry lookup |
| AI research                                | 30-120 seconds          |

For fully automated flows (Company Verification, screening), expect **2-5 minutes** end to end. Flows that require user interaction (Person Verification document capture) add human time on top. Once the user submits, server-side processing completes in 30-60 seconds.

## Two Execution Models

Zenoo supports synchronous and asynchronous execution.

| Aspect               | Sync (Model 1)                                 | Async (Model 2)                                 |
| -------------------- | ---------------------------------------------- | ----------------------------------------------- |
| **Endpoint**         | `POST /api/gateway/execute/{project_hash}/api` | `POST /api/gateway/execute/{project_hash}/init` |
| **Header**           | `X-SYNC-TIMEOUT: 30000` (ms)                   | None required                                   |
| **Response**         | Full results (or partial + tokens on timeout)  | Tokens only (`pull` + `start`)                  |
| **Blocking**         | Yes, up to timeout                             | No                                              |
| **User interaction** | Not supported                                  | Supported via `start` token                     |
| **Best for**         | Screening, Company, server-to-server           | Person with document capture, biometrics        |
| **Typical latency**  | 10-60 seconds                                  | Instant (tokens), results in 30s-5min           |

**Quick rule:** server-to-server checks use sync. User-facing journeys use async.

See [Sync vs Async](/guides/sync-vs-async) for implementation details, code examples, and timeout recommendations.

## Data Flow

The end-to-end flow from submission to results follows six steps:

1. **Submit entity data** to the Zenoo Gateway via the API (`/api` for sync, `/init` for async).
2. **Zenoo initiates configured checks** across providers -- screening, registry, document verification -- based on the flow configuration.
3. **Provider results stream back** to Zenoo as each check completes.
4. **Zenoo normalizes results**, applies the risk model, generates alerts for any hits or mismatches, and assembles the compliance report.
5. **(Optional) Salesforce case management** enriches results with AI research, UBO discovery, risk assessment, and compliance review.
6. **Retrieve aggregated results** via sync response body, pull token polling, or webhook delivery.

## Result Delivery

Zenoo supports three methods for delivering verification results to your system.

### Pull via Token (simplest)

Poll `GET /sharable-payload/{pull_token}` at intervals. Returns `204` while processing, `200` with full results when complete. Pull tokens remain valid for 30 days after results are available.

### Webhook Push (real-time)

Zenoo POSTs the full compliance report to your webhook endpoint when processing finishes. Payloads are signed with HMAC-SHA256 for verification. Fastest delivery, but requires you to expose and maintain a webhook endpoint.

### Ping + Pull (recommended for production)

<Tip>
  Use Ping + Pull for production deployments. Zenoo sends a lightweight notification to your webhook, then you fetch the full payload from the pull endpoint at your convenience. This combines real-time notification with small webhook payloads and on-demand data retrieval.
</Tip>

Zenoo sends a lightweight notification (status + pull token, no result data) to your webhook. You then fetch the full payload from the pull endpoint at your convenience. Combines real-time notification with small webhook payloads and on-demand data retrieval.

| Method         | Complexity | Latency                   | Best For                              |
| -------------- | ---------- | ------------------------- | ------------------------------------- |
| Pull via Token | Lowest     | 10-30s (poll interval)    | POC, development, simple integrations |
| Webhook Push   | Medium     | Near-instant              | Event-driven architectures            |
| Ping + Pull    | Medium     | Near-instant notification | Production systems, high reliability  |

See [Result Delivery](/guides/result-delivery) for implementation details, polling strategies, and webhook signature verification.

## Salesforce Enrichment Pipeline

When Salesforce case management is enabled, Zenoo automatically webhooks check results to Salesforce. The enrichment pipeline performs:

1. **Case creation** -- Creates an AML case (Onboarding, Review, or Perpetual) with the primary entity.
2. **Entity extraction** -- Creates case entities for each director, UBO, and shareholder from the submitted data and registry results.
3. **Risk model evaluation** -- Applies the configured risk model to determine risk tier and required verification checks.
4. **Auto-execute checks** -- Queues and executes API-based verification checks based on risk model requirements.
5. **AI research** -- Runs automated company and person intelligence gathering using public data sources.
6. **UBO discovery** -- Discovers beneficial ownership structure from registry data, supplements any UBOs provided in the original submission.
7. **Alert generation** -- Creates alerts for PEP hits, sanctions hits, adverse media, name mismatches, DOB mismatches, and other anomalies.
8. **Risk assessment** -- Evaluates multi-dimensional risk (entity-attribute, country, industry, screening) and assigns an overall risk tier.
9. **Audit trail** -- Records all compliance-relevant events with timestamps for regulatory reporting.

Enriched data flows back to Zenoo and is included in the compliance report served via the pull token or webhook.

## What's Next

<Columns cols={2}>
  <Card title="Getting Started" icon="rocket" href="/getting-started/overview">
    Create your first verification in 5 minutes
  </Card>

  <Card title="Company Verification Quickstart" icon="building" href="/use-cases/kyb-verification">
    Run company verification checks with screening and registry lookup
  </Card>

  <Card title="Person Verification Quickstart" icon="user" href="/use-cases/kyc-verification">
    Run individual identity verification with document capture
  </Card>

  <Card title="Screening Quickstart" icon="magnifying-glass" href="/use-cases/screening">
    Screen entities against PEP, sanctions, and adverse media databases
  </Card>

  <Card title="Sync vs Async" icon="arrows-split-up-and-left" href="/guides/sync-vs-async">
    Choose between synchronous and asynchronous execution models
  </Card>

  <Card title="Result Delivery" icon="paper-plane" href="/guides/result-delivery">
    Configure how you receive verification results
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Set up webhook endpoints for real-time event delivery
  </Card>
</Columns>