Skip to main content

​
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:
  1. Creates verification requirements based on entity type and role
  2. Executes API-based checks (screening, registry, identity)
  3. Generates alerts for any hits (PEP, sanctions, adverse media)
  4. Calculates a 4-dimension risk score
1

Create a company entity

Register the company you want to onboard. The response includes the entity token used in all subsequent calls.
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"
      }
    ]
  }'
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" }
  ]
}
2

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:
{
  "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.
3

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:
{
  "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 }
}
4

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"
5

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:
{
  "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 }
}
6

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:
{
  "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.
7

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:
{
  "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