> ## 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. # Generate compliance report > Generate a comprehensive compliance report for a case, including entity details, check results, alert resolutions, risk assessment, and audit trail. The report is suitable for regulatory submission and internal records. ## OpenAPI ````yaml /zenoo-api-openapi.yaml get /v1/cases/{case_token}/compliance-report 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/cases/{case_token}/compliance-report: get: tags: - Cases summary: Generate compliance report description: > Generate a comprehensive compliance report for a case, including entity details, check results, alert resolutions, risk assessment, and audit trail. The report is suitable for regulatory submission and internal records. operationId: getCaseComplianceReport parameters: - name: case_token in: path required: true description: Case token. schema: type: string - name: format in: query description: Report output format. schema: type: string enum: - json - pdf default: json responses: '200': description: Compliance report. content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/ComplianceReport' application/pdf: schema: type: string format: binary '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: 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. ComplianceReport: type: object description: > Comprehensive compliance report for a case, suitable for regulatory submission. Includes entity details, check results, alert resolutions, risk assessment, and audit trail. properties: case_token: type: string case_name: type: string case_type: type: string case_status: type: string decision: type: string nullable: true entities: type: array items: $ref: '#/components/schemas/Entity' checks: type: array items: $ref: '#/components/schemas/Check' alerts: type: array items: $ref: '#/components/schemas/Alert' risk_assessment: $ref: '#/components/schemas/RiskAssessment' timeline: type: array items: $ref: '#/components/schemas/AuditLog' generated_at: type: string format: date-time 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). Check: type: object description: > A verification check executed against a specific provider. Checks are the atomic units of verification — each produces a pass/fail/refer result. Valid results from prior checks can be reused across cases. properties: token: type: string description: Unique check identifier with `chk_` prefix. example: chk_5n8p3q1r entity_token: type: string description: Token of the entity this check verifies. type_code: type: string description: Check type code identifying the verification type. category: type: string enum: - Identity - Screening - Company - Financial - EDD description: > Check category. - `Identity` — Document OCR, biometric liveness, face match (valid 365 days) - `Screening` — PEP, sanctions, adverse media, watchlist (valid 90 days) - `Company` — Registry lookup, corporate structure (valid 180 days) - `Financial` — Source of funds, transaction monitoring (valid 365 days) - `EDD` — Enhanced due diligence, deep research (valid 180 days) status: type: string enum: - Pending - Queued - In Progress - Awaiting Document - Awaiting Client - Complete - Failed - Waived - Cancelled - Reused - Retry Scheduled description: | Current check status. - `Pending` — Check is created but not yet queued - `Queued` — Check is queued for execution - `In Progress` — Check is currently running against the provider - `Awaiting Document` — Check requires a document upload - `Awaiting Client` — Check requires client action - `Complete` — Check finished with a result - `Failed` — Check failed after all retry attempts - `Waived` — Check was waived with documented reason - `Cancelled` — Check was cancelled - `Reused` — Valid result from a prior check was reused - `Retry Scheduled` — Check failed and a retry is scheduled result: type: string enum: - Pass - Fail - Refer nullable: true description: | Check result (set when status is `Complete`). - `Pass` — Verification passed - `Fail` — Verification failed - `Refer` — Requires manual review provider: type: string nullable: true description: Name of the provider that executed this check. example: WorldCheck execution_method: type: string enum: - API - Document - Manual - Hybrid - Webhook description: How the check was executed. result_data: type: object nullable: true description: >- Provider-specific structured result data. Schema varies by check type and provider. alerts_generated: type: integer description: Number of alerts generated from this check's results. waive_reason: type: string nullable: true description: Reason the check was waived (present only for waived checks). retry_count: type: integer description: Number of retry attempts. default: 0 valid_until: type: string format: date-time nullable: true description: When this check result expires and re-verification is needed. executed_at: type: string format: date-time nullable: true description: When the check was executed. completed_at: type: string format: date-time nullable: true description: When the check completed. created_at: type: string format: date-time updated_at: type: string format: date-time Alert: type: object description: > A compliance alert requiring analyst review. Alerts are generated automatically when screening checks find matches (PEP, sanctions, adverse media) or when verification checks fail. Each alert has a priority score and SLA deadline. properties: token: type: string description: Unique alert identifier with `alt_` prefix. example: alt_3j7k9m2n case_token: type: string description: Token of the parent case. entity_token: type: string description: Token of the entity that generated this alert. type: type: string enum: - Identity - Screening - Company - Document - Financial - Client Input - Internal Review description: | Alert type determines the investigation workflow. - `Identity` — Identity verification discrepancy - `Screening` — PEP/sanctions/adverse media match - `Company` — Corporate structure or registry issue - `Document` — Document verification failure - `Financial` — Financial data anomaly - `Client Input` — Requires client-provided information - `Internal Review` — Requires internal team review category: type: string enum: - PEP Match - Sanctions Hit - Adverse Media - Name Mismatch - DOB Mismatch - Criminal Investigation - Regulatory Action - Watchlist Match - Ongoing Screening - RCA Match - API Failure description: > Specific alert category. Categories map to screening result types: - `PEP Match` — Politically Exposed Person match (Class 1-4) - `Sanctions Hit` — Match on OFAC, EU, UN, or HMT sanctions lists - `Adverse Media` — Negative news coverage (financial crime, fraud, etc.) - `Name Mismatch` — Name on document does not match provided data - `DOB Mismatch` — Date of birth does not match provided data - `Criminal Investigation` — Match on criminal investigation databases - `Regulatory Action` — Regulatory enforcement action found - `Watchlist Match` — Match on law enforcement watchlists - `Ongoing Screening` — New match from ongoing monitoring - `RCA Match` — Relative or Close Associate match - `API Failure` — External provider API failure status: type: string enum: - Open - Acknowledged - Resolved - False Positive - Escalated description: Current alert status. priority: type: string enum: - Critical - High - Medium - Low description: Alert priority level. priority_score: type: integer description: >- Numeric priority score (0-100). Higher scores indicate higher priority. minimum: 0 maximum: 100 sla_deadline: type: string format: date-time nullable: true description: SLA deadline for alert resolution. sla_status: type: string enum: - On Track - Warning - Critical - Breached description: Current SLA health. match_score: type: number format: float nullable: true description: >- Screening match confidence score (0-100). Present for screening alerts. minimum: 0 maximum: 100 ai_assessment: type: string nullable: true description: >- AI-generated assessment summary. Available after AI research completes. resolution_action: type: string enum: - Approve - Decline - Escalate - Request Document - Approve with Conditions nullable: true description: Resolution action taken (set when alert is resolved). resolution_rationale: type: string nullable: true description: Analyst's rationale for the resolution decision. resolved_by: type: string nullable: true description: User ID of the analyst who resolved the alert. resolved_at: type: string format: date-time nullable: true assigned_to: type: string nullable: true description: User ID of the assigned analyst. is_false_positive: type: boolean description: Whether the alert was marked as a false positive. default: false created_at: type: string format: date-time updated_at: type: string format: date-time RiskAssessment: type: object description: > A 4-dimension risk assessment that scores an entity across customer, geographic, product/service, and transaction dimensions. The overall score determines the risk tier and drives the due diligence path. properties: token: type: string description: Unique risk assessment identifier with `rsk_` prefix. example: rsk_2m6n4p8q case_token: type: string description: Token of the case this assessment belongs to. status: type: string enum: - Draft - Active - Superseded - Overridden - Approved description: | Assessment status. - `Draft` — Assessment is being calculated - `Active` — Current active assessment for the case - `Superseded` — Replaced by a newer assessment - `Overridden` — Tier was manually overridden - `Approved` — Assessment was approved by a senior reviewer overall_score: type: number format: float description: Aggregate risk score (0-100). minimum: 0 maximum: 100 tier: type: string enum: - High - Medium - Low description: | Risk tier classification derived from the overall score. - `High` (70-100) — Enhanced Due Diligence required, 6-month review - `Medium` (40-69) — Standard Due Diligence, 12-month review - `Low` (0-39) — Simplified Due Diligence, 24-36 month review dimensions: type: object description: Dimension-level score breakdown. properties: customer: $ref: '#/components/schemas/RiskDimension' geographic: $ref: '#/components/schemas/RiskDimension' product_service: $ref: '#/components/schemas/RiskDimension' transaction: $ref: '#/components/schemas/RiskDimension' due_diligence_path: type: string enum: - SDD - CDD - EDD description: | Recommended due diligence path based on the risk tier. - `SDD` — Simplified Due Diligence (Low risk) - `CDD` — Customer Due Diligence (Medium risk) - `EDD` — Enhanced Due Diligence (High risk) review_frequency: type: string enum: - 6 Months - 12 Months - 24 Months - 36 Months description: Recommended review frequency based on risk tier. override_tier: type: string enum: - High - Medium - Low nullable: true description: Manually overridden tier (present only if status is `Overridden`). override_justification: type: string nullable: true description: Justification for the tier override. approved_by: type: string nullable: true description: User ID of the approver (present only if status is `Approved`). approved_at: type: string format: date-time nullable: true model_version: type: string description: Version identifier of the risk model used for calculation. created_at: type: string format: date-time updated_at: type: string format: date-time AuditLog: type: object description: | An immutable audit log entry recording an action taken on the platform. Audit logs cannot be modified or deleted, ensuring full regulatory compliance and traceability. properties: token: type: string description: Unique audit log identifier with `aud_` prefix. example: aud_4t8u2v6w event_type: type: string description: | Event type in `resource.action` format. Examples: `case.created`, `alert.resolved`, `check.completed`, `risk_assessment.approved`, `entity.updated`. actor: type: object description: Who performed the action. properties: user_id: type: string nullable: true description: User ID (null for system-generated events). name: type: string type: type: string enum: - user - system - api description: Actor type. target_type: type: string enum: - case - alert - check - entity - risk_assessment - comment - webhook description: Type of resource that was acted upon. target_token: type: string description: Token of the resource that was acted upon. details: type: object description: Event-specific details (varies by event type). additionalProperties: true ip_address: type: string nullable: true description: IP address of the actor (for user-initiated events). created_at: type: string format: date-time description: When the event occurred (immutable). 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 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. RiskDimension: type: object description: Score and details for a single risk dimension. properties: score: type: number format: float description: Dimension score (0-100). minimum: 0 maximum: 100 weight: type: number format: float description: Weight applied to this dimension in the overall calculation (0-1). weighted_score: type: number format: float description: Score multiplied by weight. factors: type: array description: Individual risk factors contributing to this dimension's score. items: type: object properties: name: type: string description: Factor name. value: type: string description: Factor value. score_contribution: type: number format: float description: How much this factor contributed to the dimension score. responses: Unauthorized: description: Missing or invalid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: The requested resource does not exist. Verify the token is correct. 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. ````