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

# API Reference

> Two APIs, one platform — orchestrate verification flows and manage compliance workflows programmatically.

Zenoo gives you two complementary APIs. **Flow API** orchestrates verification journeys across multiple providers. **Case Management API** gives you programmatic control over the compliance workspace where your team reviews results.

Both are REST, both use JSON, both authenticate with `X-API-KEY`.

***

## Choose your API

<Columns cols={2}>
  <Card title="Flow API" icon="bolt" href="#flow-api">
    Orchestrate KYC, KYB, and screening checks across providers through a single endpoint. Submit data, Zenoo runs the checks, you get consolidated results back.
  </Card>

  <Card title="Case Management API" icon="briefcase" href="#case-management-api">
    Build on top of the compliance workspace — create cases, triage alerts, run risk assessments, and automate review workflows.
  </Card>
</Columns>

***

## Flow API

The Flow API is how you run verification checks. Instead of integrating with each provider separately, you send data to Zenoo and get a single consolidated response — company registry data, PEP/sanctions screening, document verification, and biometrics all in one call.

**Base URL**

```
https://{instance}.prod.onboardapp.io/api/gateway/execute/{project_hash}
```

### Endpoints

| Endpoint                         | Method                           | Use case                                                   |
| -------------------------------- | -------------------------------- | ---------------------------------------------------------- |
| `/api`                           | <Badge color="blue">POST</Badge> | Run a company flow synchronously                           |
| `/init`                          | <Badge color="blue">POST</Badge> | Start a company flow asynchronously — returns a token pair |
| `/kyc/api`                       | <Badge color="blue">POST</Badge> | Run a person flow synchronously                            |
| `/kyc/init`                      | <Badge color="blue">POST</Badge> | Start a person flow asynchronously — returns a token pair  |
| `/screening/api`                 | <Badge color="blue">POST</Badge> | Run PEP, sanctions, and adverse media screening            |
| `/sharable-payload/{pull_token}` | <Badge color="green">GET</Badge> | Retrieve results using a pull token                        |

### Two execution modes

<Tabs>
  <Tab title="Synchronous">
    Send data, wait for results. Best for server-to-server integrations where you can hold a connection open.

    ```bash theme={null}
    curl -X POST ".../api" \
      -H "X-API-KEY: your-api-key" \
      -H "X-SYNC-TIMEOUT: 30000" \
      -H "Content-Type: application/json" \
      -d '{"company_name": "Acme Ltd", "registration_number": "12345678", "country": "GB"}'
    ```

    Returns the full compliance report directly. If checks don't finish within the timeout, you get a `202` with a pull token to retrieve results later.
  </Tab>

  <Tab title="Asynchronous (Token-based)">
    Start a journey, get a token pair, retrieve results when ready. Best for user-facing flows with document capture or biometrics.

    **1. Get tokens**

    ```bash theme={null}
    curl -X POST ".../init" \
      -H "X-API-KEY: your-api-key" \
      -H "Content-Type: application/json" \
      -d '{"first_name": "Jane", "last_name": "Doe"}'
    ```

    ```json theme={null}
    { "tokens": { "start": "bwTX29", "pull": "MHqPED" } }
    ```

    **2. Send user to verification**

    ```
    https://onboard.prod.zenoo.io/{project_id}/?t=bwTX29
    ```

    **3. Retrieve results**

    ```bash theme={null}
    curl ".../sharable-payload/MHqPED" -H "X-API-KEY: your-api-key"
    ```
  </Tab>
</Tabs>

### Quick example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/api" \
    -H "X-API-KEY: your-api-key" \
    -H "X-SYNC-TIMEOUT: 30000" \
    -H "Content-Type: application/json" \
    -d '{
      "company_name": "Acme Holdings Ltd",
      "registration_number": "12345678",
      "country": "GB"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://instance.prod.onboardapp.io/api/gateway/execute/{project_hash}/api",
      headers={
          "X-API-KEY": "your-api-key",
          "X-SYNC-TIMEOUT": "30000",
          "Content-Type": "application/json"
      },
      json={
          "company_name": "Acme Holdings Ltd",
          "registration_number": "12345678",
          "country": "GB"
      }
  )
  report = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://instance.prod.onboardapp.io/api/gateway/execute/${projectHash}/api`,
    {
      method: "POST",
      headers: {
        "X-API-KEY": "your-api-key",
        "X-SYNC-TIMEOUT": "30000",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        company_name: "Acme Holdings Ltd",
        registration_number: "12345678",
        country: "GB"
      })
    }
  );
  const report = await response.json();
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 — Compliance report theme={null}
  {
    "verdict": "Refer",
    "risk_tier": "Medium",
    "company": {
      "name": "Acme Holdings Ltd",
      "registration_number": "12345678",
      "status": "Active",
      "jurisdiction": "GB",
      "directors": [
        { "name": "Jane Smith", "role": "Director", "appointed": "2019-03-15" }
      ]
    },
    "screening": {
      "total_hits": 2,
      "pep_matches": 1,
      "sanctions_matches": 0,
      "adverse_media_matches": 1
    },
    "risk_assessment": {
      "overall_tier": "Medium",
      "customer_risk": 45,
      "country_risk": 20,
      "product_risk": 35,
      "channel_risk": 10
    }
  }
  ```
</ResponseExample>

***

## Case Management API

The Case Management API gives you programmatic access to the compliance workspace. Use it to automate review workflows, integrate with internal systems, or build custom compliance dashboards.

**Base URL**

```
https://api.zenoo.com/v1
```

### Resources

<Columns cols={2}>
  <Card title="Entities" icon="user" href="/api-reference/introduction#entities-1">
    **6 endpoints** — Create and manage the people and companies being verified. Each entity has checks, alerts, and documents attached.
  </Card>

  <Card title="Cases" icon="folder-open" href="/api-reference/introduction#cases-1">
    **18 endpoints** — Full case lifecycle from creation to closure. Add entities, manage reviewers, track timelines, generate compliance reports.
  </Card>

  <Card title="Alerts" icon="bell" href="/api-reference/introduction#alerts-1">
    **11 endpoints** — Triage, resolve, escalate, and bulk-manage compliance alerts. Includes AI-powered research for screening matches.
  </Card>

  <Card title="Checks" icon="circle-check" href="/api-reference/introduction#checks-1">
    **3 endpoints** — View check results, re-run failed checks, or waive requirements when appropriate.
  </Card>

  <Card title="Risk Assessments" icon="shield-halved" href="/api-reference/introduction#risk-assessments-1">
    **3 endpoints** — View 4-dimension risk scores, approve assessments, or override with justification.
  </Card>

  <Card title="Audit & Analytics" icon="chart-line" href="/api-reference/introduction#audit--analytics-1">
    **4 endpoints** — Immutable audit logs and aggregated analytics for compliance reporting.
  </Card>
</Columns>

### What you can build

* **Automated triage** — Route new alerts to the right team based on category, risk tier, or entity type
* **Custom dashboards** — Pull case and alert analytics into your BI tools
* **Bulk operations** — Resolve, acknowledge, or assign hundreds of alerts in a single call
* **Workflow integration** — Trigger actions in Slack, Jira, or internal tools when cases change status
* **Compliance reporting** — Generate audit trails and SLA reports from the API

<Note>The Case Management API is documented with fully defined schemas in the OpenAPI spec. Use the sidebar to explore each resource.</Note>

***

## Authentication

Every request requires your API key:

```
X-API-KEY: your-api-key
```

Keys are project-scoped. Each project has separate **Sandbox** and **Production** keys. See [Authentication](/getting-started/authentication) for setup.

## Rate limits

| API                                  | Limit       | Burst |
| ------------------------------------ | ----------- | ----- |
| Flow sync (`/api`)                   | 100 req/min | 20    |
| Flow async (`/init`)                 | 100 req/min | 20    |
| Result polling (`/sharable-payload`) | 300 req/min | 50    |
| Screening (`/screening/api`)         | 200 req/min | 30    |
| Case Management (`/v1/*`)            | 500 req/min | 50    |

Rate limit headers are included in every response. See [Rate Limits](/reference/rate-limits) for retry strategies.

## Need help?

<Columns cols={2}>
  <Card title="Getting Started" icon="rocket" href="/getting-started/overview">
    Authentication, environments, and your first API call
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/reference/error-codes">
    Error codes, retry strategies, and troubleshooting
  </Card>
</Columns>