End-to-End Onboarding

This guide walks you through a complete company onboarding lifecycle using the Zenoo CLM API. By the end you will have created an entity, opened an onboarding case, executed compliance checks, reviewed generated alerts, and closed the case.

Prerequisites

A valid API key (see Authentication)
Base URL: https://api.zenoo.com/v1

What happens during onboarding

When you create an onboarding case, Zenoo automatically:

Creates verification requirements based on entity type and role
Executes API-based checks (screening, registry, identity)
Generates alerts for any hits (PEP, sanctions, adverse media)
Calculates a 4-dimension risk score

Create a company entity

curl -X POST https://api.zenoo.com/v1/entities \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "name": "Acme Holdings Ltd",
    "registration_number": "12345678",
    "country": "GB",
    "incorporation_date": "2015-03-15",
    "industry": "Financial Services",
    "directors": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "date_of_birth": "1980-05-20",
        "nationality": "GB",
        "role": "Director"
      }
    ],
    "ubos": [
      {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1975-11-10",
        "nationality": "GB",
        "ownership_percentage": 75,
        "role": "UBO"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.zenoo.com/v1/entities",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "type": "company",
        "name": "Acme Holdings Ltd",
        "registration_number": "12345678",
        "country": "GB",
        "incorporation_date": "2015-03-15",
        "industry": "Financial Services",
        "directors": [
            {
                "first_name": "Jane",
                "last_name": "Smith",
                "date_of_birth": "1980-05-20",
                "nationality": "GB",
                "role": "Director",
            }
        ],
        "ubos": [
            {
                "first_name": "John",
                "last_name": "Doe",
                "date_of_birth": "1975-11-10",
                "nationality": "GB",
                "ownership_percentage": 75,
                "role": "UBO",
            }
        ],
    },
)
entity = response.json()
print(entity["token"])  # ent_abc123

const response = await fetch("https://api.zenoo.com/v1/entities", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "company",
    name: "Acme Holdings Ltd",
    registration_number: "12345678",
    country: "GB",
    incorporation_date: "2015-03-15",
    industry: "Financial Services",
    directors: [
      {
        first_name: "Jane",
        last_name: "Smith",
        date_of_birth: "1980-05-20",
        nationality: "GB",
        role: "Director",
      },
    ],
    ubos: [
      {
        first_name: "John",
        last_name: "Doe",
        date_of_birth: "1975-11-10",
        nationality: "GB",
        ownership_percentage: 75,
        role: "UBO",
      },
    ],
  }),
});
const entity = await response.json();
console.log(entity.token); // ent_abc123

Response:

{
  "token": "ent_abc123",
  "type": "company",
  "name": "Acme Holdings Ltd",
  "status": "active",
  "created_at": "2026-02-16T10:00:00Z",
  "related_entities": [
    { "token": "ent_dir456", "name": "Jane Smith", "role": "Director" },
    { "token": "ent_ubo789", "name": "John Doe", "role": "UBO" }
  ]
}

Create an onboarding case

Open an onboarding case linked to the entity. Zenoo automatically creates verification requirements and begins executing API-based checks.

curl -X POST https://api.zenoo.com/v1/cases \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Onboarding",
    "entity_token": "ent_abc123",
    "priority": "Medium",
    "external_reference": "YOUR-REF-2026-0042"
  }'

response = requests.post(
    "https://api.zenoo.com/v1/cases",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "type": "Onboarding",
        "entity_token": "ent_abc123",
        "priority": "Medium",
        "external_reference": "YOUR-REF-2026-0042",
    },
)
case = response.json()
print(case["token"])  # cas_xyz789

const caseRes = await fetch("https://api.zenoo.com/v1/cases", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "Onboarding",
    entity_token: "ent_abc123",
    priority: "Medium",
    external_reference: "YOUR-REF-2026-0042",
  }),
});
const caseData = await caseRes.json();
console.log(caseData.token); // cas_xyz789

Response:

{
  "token": "cas_xyz789",
  "type": "Onboarding",
  "status": "New",
  "priority": "Medium",
  "entity_token": "ent_abc123",
  "due_date": "2026-03-02T10:00:00Z",
  "created_at": "2026-02-16T10:01:00Z"
}

The due_date is automatically calculated from SLA configuration based on case type and priority. An Onboarding/Medium case defaults to 14 calendar days.

List checks created for the case

Zenoo auto-creates checks based on entity type and role. List them to track progress.

curl -X GET "https://api.zenoo.com/v1/cases/cas_xyz789/checks" \
  -H "Authorization: Bearer your-api-key"

response = requests.get(
    "https://api.zenoo.com/v1/cases/cas_xyz789/checks",
    headers={"Authorization": "Bearer your-api-key"},
)
checks = response.json()
for check in checks["data"]:
    print(f"{check['type']} - {check['status']}")

const checksRes = await fetch(
  "https://api.zenoo.com/v1/cases/cas_xyz789/checks",
  { headers: { Authorization: "Bearer your-api-key" } }
);
const checks = await checksRes.json();
checks.data.forEach((c) => console.log(`${c.type} - ${c.status}`));

Response:

{
  "data": [
    { "token": "chk_001", "type": "PEP Screening", "category": "Screening", "entity": "Acme Holdings Ltd", "status": "In Progress" },
    { "token": "chk_002", "type": "Sanctions Screening", "category": "Screening", "entity": "Acme Holdings Ltd", "status": "In Progress" },
    { "token": "chk_003", "type": "Company Registry", "category": "Company", "entity": "Acme Holdings Ltd", "status": "Queued" },
    { "token": "chk_004", "type": "PEP Screening", "category": "Screening", "entity": "Jane Smith", "status": "Queued" },
    { "token": "chk_005", "type": "PEP Screening", "category": "Screening", "entity": "John Doe", "status": "Queued" },
    { "token": "chk_006", "type": "Identity Verification", "category": "Identity", "entity": "John Doe", "status": "Pending" }
  ],
  "meta": { "total": 6 }
}

Wait for checks to complete

Checks execute asynchronously. Use webhooks (recommended) or poll the case status.Option A: WebhookConfigure a webhook endpoint to receive check.completed and check.failed events. See Webhook Events.Option B: Poll

curl -X GET "https://api.zenoo.com/v1/cases/cas_xyz789" \
  -H "Authorization: Bearer your-api-key"

import time

while True:
    response = requests.get(
        "https://api.zenoo.com/v1/cases/cas_xyz789",
        headers={"Authorization": "Bearer your-api-key"},
    )
    case = response.json()
    if case["checks_summary"]["pending"] == 0:
        break
    time.sleep(10)

async function waitForChecks(caseToken) {
  while (true) {
    const res = await fetch(
      `https://api.zenoo.com/v1/cases/${caseToken}`,
      { headers: { Authorization: "Bearer your-api-key" } }
    );
    const data = await res.json();
    if (data.checks_summary.pending === 0) return data;
    await new Promise((r) => setTimeout(r, 10000));
  }
}

Review alerts generated

After checks complete, any screening hits generate alerts that require analyst review.

curl -X GET "https://api.zenoo.com/v1/cases/cas_xyz789/alerts" \
  -H "Authorization: Bearer your-api-key"

response = requests.get(
    "https://api.zenoo.com/v1/cases/cas_xyz789/alerts",
    headers={"Authorization": "Bearer your-api-key"},
)
alerts = response.json()
for alert in alerts["data"]:
    print(f"{alert['category']} - {alert['status']} (score: {alert['priority_score']})")

const alertsRes = await fetch(
  "https://api.zenoo.com/v1/cases/cas_xyz789/alerts",
  { headers: { Authorization: "Bearer your-api-key" } }
);
const alerts = await alertsRes.json();
alerts.data.forEach((a) =>
  console.log(`${a.category} - ${a.status} (score: ${a.priority_score})`)
);

Response:

{
  "data": [
    {
      "token": "alt_alert01",
      "type": "Screening",
      "category": "PEP Match",
      "title": "PEP Match: John Doe",
      "status": "Open",
      "priority": "High",
      "priority_score": 78,
      "match_score": 92,
      "entity_name": "John Doe",
      "sla_due_date": "2026-02-18T10:00:00Z"
    }
  ],
  "meta": { "total": 1 }
}

Resolve each alert

Review the alert details and resolve it with an action and justification.

curl -X POST https://api.zenoo.com/v1/alerts/alt_alert01/resolve \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Approve",
    "notes": "PEP match confirmed as former local councillor (2010-2014). Low risk position, no current exposure. EDD not required."
  }'

response = requests.post(
    "https://api.zenoo.com/v1/alerts/alt_alert01/resolve",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "action": "Approve",
        "notes": "PEP match confirmed as former local councillor (2010-2014). Low risk position, no current exposure. EDD not required.",
    },
)
print(response.json()["status"])  # Resolved

const resolveRes = await fetch(
  "https://api.zenoo.com/v1/alerts/alt_alert01/resolve",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action: "Approve",
      notes:
        "PEP match confirmed as former local councillor (2010-2014). Low risk position, no current exposure. EDD not required.",
    }),
  }
);
const resolved = await resolveRes.json();
console.log(resolved.status); // Resolved

Response:

{
  "token": "alt_alert01",
  "status": "Resolved",
  "resolution_action": "Approve",
  "resolved_at": "2026-02-16T11:30:00Z"
}

A case cannot be closed while it has open alerts. Resolve or escalate every alert before closing.

Close the case

Once all alerts are resolved, close the case with a summary.

curl -X POST https://api.zenoo.com/v1/cases/cas_xyz789/close \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_notes": "Company verified. Registry check passed. One PEP match on UBO (former local councillor) reviewed and approved. Risk tier: Medium."
  }'

response = requests.post(
    "https://api.zenoo.com/v1/cases/cas_xyz789/close",
    headers={
        "Authorization": "Bearer your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "resolution_notes": "Company verified. Registry check passed. One PEP match on UBO (former local councillor) reviewed and approved. Risk tier: Medium.",
    },
)
print(response.json()["status"])  # Closed

const closeRes = await fetch(
  "https://api.zenoo.com/v1/cases/cas_xyz789/close",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      resolution_notes:
        "Company verified. Registry check passed. One PEP match on UBO (former local councillor) reviewed and approved. Risk tier: Medium.",
    }),
  }
);
const closed = await closeRes.json();
console.log(closed.status); // Closed

Response:

{
  "token": "cas_xyz789",
  "status": "Closed",
  "risk_tier": "Medium",
  "risk_score": 45,
  "completed_at": "2026-02-16T11:35:00Z",
  "checks_summary": { "total": 6, "passed": 5, "referred": 1, "failed": 0 }
}

Next steps

Alert Review. Triage and resolve alerts in bulk via the API.
Case Lifecycle Guide. Understand all status transitions and SLA rules.
Check Orchestration Guide. Learn how checks are auto-created and executed.
Webhook Events. Set up real-time notifications for case and check events.

Getting Started

Use-Case Guides

Platform Concepts

Domain Concepts

Data Model

End-to-End Onboarding

End-to-End Onboarding

Prerequisites

What happens during onboarding

Next steps

​End-to-End Onboarding

​Prerequisites

​What happens during onboarding

​Next steps

End-to-End Onboarding

Prerequisites

What happens during onboarding

Next steps