> ## 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. # List entities with filters > Retrieve entities with optional filtering by type, verification status, or case association. Results are sorted by creation date (newest first). ## OpenAPI ````yaml /zenoo-api-openapi.yaml get /v1/entities openapi: 3.1.0 info: title: Zenoo API version: 3.0.0 summary: >- Unified compliance platform API — orchestration, case management, and screening description: > > **Welcome to the Zenoo API v3** > > Zenoo is a unified compliance platform that combines verification orchestration > (Studio) with case management (CLM) through a single API surface. Submit entity > data, run checks, manage investigations, and track compliance decisions — all > through one integration. ## Platform Architecture ``` Your System ──► Zenoo API v3 │ ├── Studio (Orchestration) │ ├── Flow execution (sync / async) │ ├── Provider routing (WorldCheck, Sumsub, ComplyAdvantage) │ └── Structured results with risk scoring │ └── CLM (Case Management) ├── Case lifecycle (create → investigate → close) ├── Alert triage (auto-priority, SLA tracking) ├── Risk assessment (4-dimension scoring) ├── Audit trail (immutable compliance log) └── AI-powered research and disposition ``` ## Key Concepts | Concept | Description | Token Prefix | |---------|-------------|--------------| | **Flow** | Orchestration template that defines which checks to run | `flw_` | | **Case** | Investigation container — groups entities, alerts, and checks | `cas_` | | **Entity** | Person or company under investigation | `ent_` | | **Alert** | Issue requiring analyst review (PEP match, sanctions hit, etc.) | `alt_` | | **Check** | Verification action (screening, identity, document, company) | `chk_` | | **Risk Assessment** | 4-dimension risk score with tiered classification | `rsk_` | | **Comment** | Analyst note, decision record, or system event on a case | `cmt_` | | **Audit Log** | Immutable record of every action taken on the platform | `aud_` | ## Authentication All requests require authentication via one of two methods: | Method | Header | Use Case | |--------|--------|----------| | **API Key** | `X-API-KEY: ` | Server-to-server integrations | | **OAuth 2.0** | `Authorization: Bearer ` | Application-level access with scoped permissions | API keys are project-scoped. Staging and production use different keys. Never expose API keys in client-side code. ## Pagination All list endpoints use cursor-based pagination: ```json { "data": [...], "meta": { "cursor": "eyJpZCI6ImNhc18xMjM0In0=", "has_more": true } } ``` Pass the `cursor` value as a query parameter to fetch the next page. Default page size is 25; maximum is 100. ## Idempotency All mutation endpoints (POST, PATCH, DELETE) support the `Idempotency-Key` header. Send the same key within 24 hours to safely retry requests without duplicate side effects. ## Rate Limits | Plan | Requests/min | Burst | |------|-------------|-------| | Starter | 60 | 10 | | Professional | 300 | 50 | | Enterprise | 1000 | 200 | Rate limit headers are included in every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. ## Versioning This API follows semantic versioning. The current version is **v3.0.0**. Breaking changes are communicated via email and changelog at least 30 days in advance. contact: name: Zenoo Developer Support email: support@zenoo.com url: https://zenoo.com license: name: Proprietary url: https://zenoo.com/terms servers: - url: https://instance.prod.onboardapp.io description: Production (replace "instance" with your subdomain) - url: https://instance.staging.onboardapp.io description: Staging (replace "instance" with your subdomain) - url: https://api.zenoo.com description: Case Management API security: - ApiKeyAuth: [] tags: - name: Flow API description: > Submit entity data for compliance verification — company registry lookups, person identity checks, and AML screening. The Flow API supports three flow types, each available in synchronous and asynchronous modes. ## Flow Types | Type | Endpoint Pattern | Description | |------|-----------------|-------------| | **Company** | `/api/gateway/execute/{project_hash}/api` (sync) | Registry lookup + director/UBO screening | | **Company** | `/api/gateway/execute/{project_hash}/init` (async) | Same checks, returns tokens immediately | | **Person** | `/api/gateway/execute/{project_hash}/kyc/api` (sync) | Identity + screening (server-side) | | **Person** | `/api/gateway/execute/{project_hash}/kyc/init` (async) | Identity + document capture + biometrics | | **Screening** | `/api/gateway/execute/{project_hash}/screening/api` | Standalone PEP/sanctions/adverse media check | | **Results** | `GET /api/gateway/sharable-payload/{pull_token}` | Retrieve async verification results | ## Capabilities | Capability | Description | |-----------|-------------| | **Sync execution** | Block until all checks complete (with configurable timeout via `X-SYNC-TIMEOUT`) | | **Async execution** | Initiate verification, retrieve results via pull token or webhook | | **Multi-provider** | Route checks across WorldCheck, Sumsub, ComplyAdvantage, and more | | **Idempotency** | Use `external_reference` to prevent duplicate verifications | | **Verification URLs** | Generate hosted verification journeys for document capture + biometrics | ## Execution Models ``` Sync: POST /api (or /kyc/api) ──► Checks Run ──► Full Results Returned (200) └──► Timeout ──► Partial Results + Tokens (202) Async: POST /init (or /kyc/init) ──► Tokens Returned (200) ├──► GET /sharable-payload/{pull} ──► Results └──► Webhook delivery (recommended) ``` > **Use sync** for server-to-server checks (screening, registry lookups) where you need results immediately. > **Use async** for client-facing journeys (document capture, biometric liveness) or when processing may exceed timeout. - name: Entities description: > Manage person and company entities under compliance investigation. Entities are the subjects of verification — they belong to cases, receive checks, and generate alerts when screening matches are found. ## Capabilities | Capability | Description | |-----------|-------------| | **Create** | Register a person or company entity with identifying data | | **Update** | Patch entity attributes as new information becomes available | | **List checks** | View all verification checks associated with an entity | | **List alerts** | View all alerts generated from entity screening results | ## Entity Types | Type | Key Fields | Typical Checks | |------|-----------|----------------| | **Person** | first_name, last_name, date_of_birth, nationality | Identity, Screening, Document | | **Company** | company_name, registration_number, country | Company registry, Corporate screening | ## Entity Roles | Role | Description | |------|-------------| | `Primary` | The main subject of the case | | `UBO` | Ultimate Beneficial Owner (>=25% ownership) | | `Director` | Company director or officer | | `Shareholder` | Company shareholder below UBO threshold | - name: Cases description: > Manage the full lifecycle of compliance investigation cases. A case groups entities, alerts, checks, risk assessments, and audit trails into a single investigation unit. ## Capabilities | Capability | Description | |-----------|-------------| | **Lifecycle management** | Create, update, close, escalate cases | | **Entity management** | Add persons and companies to a case | | **Alert aggregation** | View all alerts across case entities | | **Risk assessment** | Calculate and manage 4-dimension risk scores | | **Collaboration** | Comments, reviewers, and compliance reports | | **Audit trail** | Immutable timeline of all case actions | ## Case Lifecycle ``` New ──► In Progress ──► In Review ──► Closed │ │ │ │ ├──► Client Input ──┘ │ │ │ └──► Internal Review ──┘ │ └──► Escalated ``` ## Case Types | Type | Description | Typical Duration | |------|-------------|-----------------| | `Onboarding` | New customer due diligence | 1-5 business days | | `Review` | Periodic review of existing customer | 5-15 business days | | `Perpetual` | Ongoing monitoring case (no fixed end) | Continuous | - name: Alerts description: > Triage, investigate, and resolve compliance alerts. Alerts are generated automatically when screening checks find matches (PEP, sanctions, adverse media) or when verification checks fail. Each alert requires analyst review and resolution. ## Capabilities | Capability | Description | |-----------|-------------| | **Triage** | Acknowledge, assign, and prioritize alerts | | **Resolution** | Resolve as true positive, false positive, or escalate | | **Bulk operations** | Resolve, acknowledge, or assign multiple alerts at once | | **AI research** | Trigger AI-powered research for deeper investigation | | **SLA tracking** | Automatic priority scoring and deadline management | ## Alert Lifecycle ``` Open ──► Acknowledged ──► Resolved │ │ │ │ │ (False Positive) │ │ └──► Escalated ``` ## Alert Categories | Category | Source | Typical Priority | |----------|--------|-----------------| | `PEP Match` | Screening provider | High | | `Sanctions Hit` | Screening provider | Critical | | `Adverse Media` | Screening provider | Medium-High | | `Name Mismatch` | Identity check | Medium | | `DOB Mismatch` | Identity check | Medium | | `Watchlist Match` | Screening provider | High | | `API Failure` | System | Low | - name: Checks description: > Execute and manage verification checks on entities. Checks are the atomic units of verification — each check runs against a specific provider and produces a pass/fail/refer result. ## Capabilities | Capability | Description | |-----------|-------------| | **Execute** | Trigger a check to run against its configured provider | | **Waive** | Mark a check as waived with a documented reason | | **Reuse** | Automatically reuse valid results from prior checks | | **Status tracking** | Monitor check progress through its lifecycle | ## Check Categories | Category | Examples | Typical Providers | |----------|---------|-------------------| | `Identity` | Document OCR, biometric liveness, face match | Sumsub | | `Screening` | PEP, sanctions, adverse media, watchlist | WorldCheck, ComplyAdvantage | | `Company` | Registry lookup, corporate structure | Registry providers | | `Financial` | Source of funds, transaction monitoring | Financial data providers | | `EDD` | Enhanced due diligence, deep research | AI services | ## Check Lifecycle ``` Pending ──► Queued ──► In Progress ──► Complete (Pass/Fail/Refer) │ ├──► Awaiting Document ├──► Awaiting Client ├──► Failed ├──► Retry Scheduled └──► Cancelled ``` - name: Risk Assessments description: > Manage risk assessments that score entities across four dimensions. Risk assessments produce an overall score and tier classification (High/Medium/Low) used for due diligence path routing and SLA assignment. ## Capabilities | Capability | Description | |-----------|-------------| | **Calculate** | Run the risk model against case data to produce a score | | **Approve** | Senior reviewer approves the assessment | | **Override** | Override the calculated tier with justification | ## Risk Dimensions | Dimension | Weight | Factors | |-----------|--------|---------| | `customer` | 30% | Entity type, PEP status, sanctions, adverse media | | `geographic` | 25% | Country risk, FATF status, jurisdiction | | `product_service` | 25% | Product complexity, regulatory exposure | | `transaction` | 20% | Volume, frequency, unusual patterns | ## Risk Tiers | Tier | Score Range | Due Diligence Path | Review Frequency | |------|------------|-------------------|-----------------| | `High` | 70-100 | EDD (Enhanced) | 6 months | | `Medium` | 40-69 | CDD (Standard) | 12 months | | `Low` | 0-39 | SDD (Simplified) | 24-36 months | - name: Audit Trail description: > Access the immutable audit log that records every action taken on the platform. Audit logs are append-only and cannot be modified or deleted, ensuring full regulatory compliance and traceability. ## Capabilities | Capability | Description | |-----------|-------------| | **Query** | Filter logs by event type, actor, target, and date range | | **Case timeline** | View the complete history of a specific case | | **Compliance export** | Generate audit reports for regulatory submissions | ## Event Types | Category | Events | |----------|--------| | **Case** | case.created, case.status_changed, case.closed, case.escalated | | **Alert** | alert.created, alert.acknowledged, alert.resolved, alert.escalated | | **Check** | check.executed, check.completed, check.failed, check.waived | | **Risk** | risk_assessment.calculated, risk_assessment.approved, risk_assessment.overridden | | **Entity** | entity.created, entity.updated, entity.added_to_case | - name: Analytics description: > Access compliance metrics and statistics for dashboards, reporting, and operational monitoring. Analytics endpoints provide aggregated data across cases, alerts, and checks. ## Capabilities | Capability | Description | |-----------|-------------| | **Summary metrics** | Key compliance KPIs (open cases, pending alerts, SLA health) | | **Alert statistics** | Alert volume, resolution rates, category breakdown | | **Case statistics** | Case throughput, aging, type distribution | - name: Webhooks description: > Register and manage webhook endpoints to receive real-time notifications when events occur on the platform. Webhook payloads are signed with HMAC-SHA256 for verification. ## Events | Event | Trigger | Typical Latency | |-------|---------|----------------| | `case.created` | New case is created | <5 seconds | | `case.status_changed` | Case status transitions | <5 seconds | | `case.closed` | Case is closed | <5 seconds | | `case.escalated` | Case is escalated | <5 seconds | | `alert.created` | New alert is generated | <5 seconds | | `alert.resolved` | Alert is resolved | <5 seconds | | `alert.escalated` | Alert is escalated | <5 seconds | | `check.completed` | Check finishes successfully | <5 seconds | | `check.failed` | Check fails after retries | After last retry | | `risk_assessment.completed` | Risk score calculated | <5 seconds | | `risk_assessment.approved` | Assessment approved | <5 seconds | | `sla.warning` | SLA deadline approaching | At warning threshold | | `sla.breached` | SLA deadline passed | At breach time | ## Signature Verification Every webhook includes an `X-Zenoo-Signature` header containing `sha256=` followed by the hex-encoded HMAC-SHA256 digest of the raw request body, computed with your webhook secret. **Verify signatures using constant-time comparison:** | Language | Function | |----------|----------| | Node.js | `crypto.timingSafeEqual()` | | Python | `hmac.compare_digest()` | | Java | `MessageDigest.isEqual()` | | Go | `hmac.Equal()` | ## Retry Schedule | Attempt | Delay | |---------|-------| | 1st retry | 1 minute | | 2nd retry | 5 minutes | | 3rd retry | 30 minutes | | 4th retry | 1 hour | | 5th-168th | Every 1 hour for 7 days | After 7 days of consecutive failures, the webhook is marked as undeliverable. - name: Comments description: > Manage discussion and collaboration on cases. Comments support analyst notes, formal decisions, system-generated events, and user mentions for team coordination. ## Comment Types | Type | Description | Created By | |------|-------------|-----------| | `Comment` | Free-form analyst note or observation | Analyst | | `Decision` | Formal decision record (approve, decline, escalate) | Senior reviewer | | `Note` | Internal note not visible to external parties | Any user | | `System` | Auto-generated event record (status change, assignment) | System | paths: /v1/entities: get: tags: - Entities summary: List entities with filters description: | Retrieve entities with optional filtering by type, verification status, or case association. Results are sorted by creation date (newest first). operationId: listEntities parameters: - $ref: '#/components/parameters/CursorParam' - $ref: '#/components/parameters/LimitParam' - name: type in: query description: Filter by entity type. schema: type: string enum: - Person - Company - name: verification_status in: query description: Filter by verification status. schema: type: string enum: - Not Started - In Progress - Verified - Expired - Failed - name: case_token in: query description: Filter entities belonging to a specific case. schema: type: string responses: '200': description: List of entities. content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Entity' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: parameters: CursorParam: name: cursor in: query description: Pagination cursor from a previous response. Pass to fetch the next page. schema: type: string LimitParam: name: limit in: query description: Maximum number of items to return per page. schema: type: integer default: 25 minimum: 1 maximum: 100 schemas: ApiResponse: type: object description: | Standard response wrapper for all API endpoints. Contains the resource data and pagination metadata. properties: data: description: Response payload. Type varies by endpoint. meta: type: object properties: request_id: type: string description: Unique request identifier for debugging and support. example: req_9k4m2n1p3q page: type: object description: Pagination metadata (present on list endpoints). properties: cursor: type: string nullable: true description: Cursor for fetching the next page. Null if no more pages. has_more: type: boolean description: Whether more results are available. Entity: type: object description: > A person or company entity under compliance investigation. Entities are the subjects of verification checks and may generate alerts when screening matches are found. An entity can belong to multiple cases with different roles. properties: token: type: string description: Unique entity identifier with `ent_` prefix. example: ent_8f3k2m1n type: type: string enum: - Person - Company description: Entity type — determines which fields are applicable. first_name: type: string description: Person first name. Present only for Person entities. example: John last_name: type: string description: Person last name. Present only for Person entities. example: Smith full_name: type: string description: | Computed full name. For persons: `first_name + last_name`. For companies: same as `company_name`. example: John Smith company_name: type: string description: Company legal name. Present only for Company entities. date_of_birth: type: string format: date description: Person date of birth (YYYY-MM-DD). Present only for Person entities. nationality: type: string description: >- ISO 3166-1 alpha-2 nationality code. Present only for Person entities. example: GB registration_number: type: string description: Company registration number. Present only for Company entities. country: type: string description: >- ISO 3166-1 alpha-2 country code for the entity's primary jurisdiction. example: GB role: type: string enum: - Primary - UBO - Director - Shareholder description: | Entity's role within its case context. - `Primary` — The main subject of the investigation - `UBO` — Ultimate Beneficial Owner (>=25% ownership) - `Director` — Company director or officer - `Shareholder` — Shareholder below UBO threshold verification_status: type: string enum: - Not Started - In Progress - Verified - Expired - Failed description: | Current verification status of the entity. - `Not Started` — No checks have been initiated - `In Progress` — Checks are currently running - `Verified` — All required checks passed - `Expired` — Verification has expired and needs renewal - `Failed` — One or more checks failed address: $ref: '#/components/schemas/Address' checks_summary: type: object description: Summary counts of associated checks. properties: total: type: integer complete: type: integer pending: type: integer failed: type: integer alerts_summary: type: object description: Summary counts of associated alerts. properties: total: type: integer open: type: integer resolved: type: integer external_reference: type: string description: Your internal reference ID for this entity. created_at: type: string format: date-time description: When the entity was created (ISO 8601). updated_at: type: string format: date-time description: When the entity was last updated (ISO 8601). Address: type: object description: Structured address. properties: line1: type: string description: Street address line 1. line2: type: string description: Street address line 2. city: type: string state: type: string description: State, province, or region. postal_code: type: string country: type: string description: ISO 3166-1 alpha-2 country code. ErrorResponse: type: object description: > Standard error response. All errors include a machine-readable `code`, human-readable `message`, and a `request_id` for support troubleshooting. properties: error: type: object required: - code - message - request_id properties: code: type: string description: > Machine-readable error code. Use this for programmatic error handling. | Code | HTTP | Description | Retry? | |------|------|-------------|--------| | `VALIDATION_ERROR` | 400 | Malformed request body or parameters | No | | `INVALID_JSON` | 400 | Request body is not valid JSON | No | | `UNAUTHORIZED` | 401 | Invalid or missing API key | No | | `FORBIDDEN` | 403 | Insufficient permissions | No | | `NOT_FOUND` | 404 | Resource does not exist | No | | `TOKEN_EXPIRED` | 404 | Pull or start token has expired | No | | `RATE_LIMITED` | 429 | Rate limit exceeded | Yes (after reset) | | `INTERNAL_ERROR` | 500 | Unexpected server error | Yes (with backoff) | | `PROVIDER_ERROR` | 502 | External provider failure | Yes (with backoff) | | `SERVICE_UNAVAILABLE` | 503 | Service temporarily unavailable | Yes (with backoff) | enum: - VALIDATION_ERROR - INVALID_JSON - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - TOKEN_EXPIRED - RATE_LIMITED - INTERNAL_ERROR - PROVIDER_ERROR - SERVICE_UNAVAILABLE message: type: string description: Human-readable error description. details: type: array description: Field-level validation errors (present for `validation_error`). items: type: object properties: field: type: string description: JSON path to the invalid field. message: type: string description: Description of the validation failure. code: type: string description: >- Field-level error code (e.g., `required`, `invalid_format`). request_id: type: string description: > Unique request identifier. Include this when contacting Zenoo support for faster issue resolution. example: req_9k4m2n1p3q responses: Unauthorized: description: Missing or invalid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' TooManyRequests: description: >- Rate limit exceeded. Retry after the time indicated in the `X-RateLimit-Reset` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' InternalError: description: >- Unexpected server error. Include the `request_id` from the error response when contacting support. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-RateLimit-Limit: description: Maximum requests allowed per minute for your plan. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in the current rate limit window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the rate limit window resets. schema: type: integer securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: | Project-scoped API key for server-to-server authentication. Obtain keys from the Zenoo dashboard under Project Settings > API Keys. Staging and production environments use separate keys. ````