Documentation & Guides

KYC-Agent is a cloud-native compliance platform that automates identity verification, sanctions screening, and risk scoring for individuals and businesses worldwide. This guide walks you through your very first session from inbox invitation to an approved verification.

Accepting Your Invitation

Your organisation administrator sends an invitation email containing a one-time setup link. The link is valid for 72 hours. Follow these steps to activate your account:

1. Open the invitation email

   Click Accept Invitation. If the link has expired, contact your admin to resend it.

2. Set a strong password

   Minimum 12 characters including at least one uppercase letter, one number, and one symbol. Passphrases (e.g. Cobalt-Train-92-Lantern) are strongly recommended.

3. Enable Multi-Factor Authentication (MFA)

   Scan the QR code with an authenticator app (Google Authenticator, Authy, or Microsoft Authenticator). Enter the 6-digit code to verify and complete setup.

4. Save your backup codes

   You are shown 10 single-use recovery codes. Store them offline in a secure location. They are required if you lose access to your authenticator device.

Logging In

Navigate to https://app.kyc-agent.com and enter your email and password. After a successful password check, you will be prompted for your MFA code. You will land on your personalised dashboard showing pending verifications, recent alerts, and your work queue.

Browser Requirements

KYC-Agent is optimised for modern browsers. For the best experience use the latest stable version of Chrome, Firefox, Edge, or Safari. Internet Explorer is not supported.

KYC-Agent uses role-based access control (RBAC) to ensure users can only see and action data appropriate for their responsibilities. Your role is assigned by an Admin when your account is created. It controls which modules are visible, what data you can read or write, and which decisions you are authorised to make.

Available Roles at a Glance

What a Viewer Can Do

Viewers have comprehensive read access but zero write access. You can:

• Browse all cases, verification results, and entity profiles
• View all report dashboards and download scheduled reports
• Inspect the audit trail for any action or decision
• Filter and search across the entity registry

You cannot submit verifications, add case notes, make decisions, or access Settings.

What an Analyst Can Do

Analysts handle the day-to-day verification workload. You can do everything a Viewer can, plus:

• Submit new individual and business verifications via the UI
• Upload supporting documents and add case notes
• Approve cases with a risk score below your organisation's auto-review threshold (typically 30)
• Flag a case for escalation to a Compliance Officer
• Request re-verification on an existing entity

What a Compliance Officer Can Do

Compliance Officers hold the highest decision-making authority for day-to-day compliance tasks. In addition to Analyst capabilities, you can:

• Approve or reject cases at any risk score — including high-risk cases above 70
• Trigger Enhanced Due Diligence (EDD) on any entity
• Draft and submit Suspicious Activity Reports (SARs)
• Export case data, audit logs, and compliance reports in PDF/CSV
• Override an automated decision and document the reasoning
• Manage perpetual KYC schedules for an entity

How Roles Affect What You See

Menus, buttons, and entire pages adapt dynamically to your role. For example, the Settings menu is only visible to Admins and above. The Reject button on a case is only enabled for Compliance Officers and above. If you believe you are missing access you need, contact your Admin to review your role assignment.

The dashboard is your operational command centre. It is personalised to your role, showing the data most relevant to your daily tasks.

Overview Panel

At the top of the dashboard you will find four metric cards: Total Pending, Approved Today, Risk Alerts, and SLA At Risk. These update every 30 seconds without a page refresh. Clicking any card navigates to the corresponding filtered case list.

Your Work Queue

Cases assigned to you appear in the My Queue widget. Cases are sorted by priority score (highest first) by default. The columns are:

Main Navigation Modules

The left sidebar contains the primary navigation. Modules visible to you depend on your role:

• Dashboard — Overview metrics and your personal queue
• Verifications — All verifications: pending, completed, flagged
• Entities — Searchable registry of all individuals and businesses ever verified
• Cases — Active cases awaiting decision (Analysts and above)
• Alerts — Real-time feed of system-generated flags and monitoring hits
• Reports — Dashboards and exportable compliance reports
• Audit Log — Immutable record of every action (visible to all roles)
• Settings — Org-level configuration (Admin and above only)

Search & Filters

Use the global search bar (Ctrl+K / ⌘+K) to find any entity, case, or document instantly. On list pages, the filter panel on the right allows multi-dimensional filtering by status, risk score range, entity type, date range, and assigned user.

There are two ways to initiate a verification: through the UI (covered here) or via the REST API (covered in the Advanced User Guide). You need at minimum the Analyst role to submit.

Choose Entity Type

Navigate to Verifications → New Verification. Select whether you are verifying an Individual or a Business. This determines the document checklist and the checks that are run.

Required Documents

Upload & Submit Walkthrough

1. Enter the subject's basic details

   Fill in the full legal name, date of birth (for individuals), country of incorporation or residence, and any reference number from your own system (for matching results back to your records).

2. Upload the primary identity document

   Drag-and-drop or click Browse to upload. Supported formats: JPEG, PNG, HEIC, PDF. Maximum file size: 10 MB. The image must show the full document including all four corners with no glare or cropping.

3. Complete liveness capture (individuals only)

   Click Start Liveness Check and follow the on-screen prompts. The subject must be physically present — the AI will reject static photos, printed images, and deepfake video replays.

4. Select the verification rule set

   Choose the applicable rule set from the dropdown (e.g. Standard KYC, Enhanced Due Diligence, KYB — Low Complexity). Your Admin configures the available options. If unsure, use the default.

5. Submit and monitor

   Click Submit Verification. The platform runs all configured checks automatically. A progress indicator shows which checks are running. Standard cases complete within 30–60 seconds; EDD cases may take longer.

The Automated Check Pipeline

Once submitted, the platform runs checks in this order:

1. OCR Extraction — Parse text fields from all document zones (MRZ, visual zone, barcodes)
2. Document Authenticity — Detect forgeries, alterations, and font/metadata anomalies
3. Biometric Liveness Detection — Confirm a live person presented the document
4. Face Match — Compare live selfie to the document portrait (threshold: ≥ 97% match score)
5. Sanctions Screening — Cross-reference against OFAC SDN, EU Consolidated, UN SC, HM Treasury, and 200+ additional lists
6. PEP Check — Identify Politically Exposed Persons and their associates
7. Adverse Media Search — NLP-powered global news scan for negative coverage
8. Risk Score Calculation — Weighted composite score from all check results

Each completed verification generates a structured result page containing the risk score, per-check outcomes, flagged matches, and supporting evidence. Understanding these results is essential for making correct compliance decisions.

The Risk Score

The composite risk score (0–100) is a weighted average of all sub-check results. Lower is better. The score drives the automatic routing decision:

Individual Check Results

Below the risk score, each sub-check is listed with a status badge: Pass (green), Review (amber), or Fail (red). Click any row to expand it and see:

• The raw extracted data or matched records
• The confidence score from the AI model
• The specific list or source that generated a flag
• A plain-English explanation of why the check passed or failed

Evidence Panel

The Evidence tab on the right side of the result page shows all documents, screenshots, and raw API responses associated with the verification. All evidence is preserved in tamper-evident storage and is included in any exported compliance report.

When a verification requires human decision-making (amber or red risk scores), a Case is automatically created and assigned to the appropriate queue. Cases are the primary unit of compliance work in KYC-Agent.

Opening a Case

From your work queue, click a case row to open the Case Detail view. This contains:

• The verification result summary with risk score and check outcomes
• The entity profile with history of all previous verifications
• The case timeline showing every event and decision chronologically
• The notes thread for team collaboration
• The decision panel (visible to authorised roles)

Adding Notes

Good case notes are critical for compliance audit trails. Add a note by clicking Add Note in the timeline. Notes are attributed to you with a timestamp and are immutable — once saved, notes cannot be edited or deleted. When writing notes:

• Be specific: reference the evidence you examined (e.g. "Reviewed passport scan — MRZ matches visual zone, no signs of tampering")
• Explain your reasoning if dismissing a flag (e.g. "Sanctions name match dismissed — DOB does not match OFAC entry, different nationality")
• Tag colleagues using @username to draw their attention to a specific point

Making a Decision

The decision buttons appear at the bottom of the Case Detail view. What you can do depends on your role and the case risk score:

Reassigning Cases

If you need to transfer a case to a colleague, click Reassign from the case action menu (⋯). Select the new assignee and optionally add a handover note. The previous owner is notified of the reassignment.

KYC-Agent runs continuous background monitoring on all entities in your active portfolio. When something changes — a new sanctions entry, an adverse media article, or a risk score shift — an alert is generated automatically.

Alert Types

Notification Channels

Alerts are delivered through:

• In-app bell (🔔) — Real-time badge count in the top navigation; click to see the alert feed
• Email digest — Configurable cadence: instant (per alert), hourly summary, or daily summary
• Webhook push — Org-level webhook that fires on every alert (configured by Admin)
• Mobile push notification — Available via the KYC-Agent mobile app (iOS and Android)

Configuring Your Notification Preferences

Go to Settings → My Preferences → Notifications to configure which alert types trigger which channels for your account. You can suppress low-priority alerts from email while keeping Critical and High priority alerts on instant delivery. Per-user settings override the organisation-wide defaults.

Access your personal settings via the avatar menu in the top-right corner of the application, then My Profile.

Updating Your Profile

You can change your display name and upload a profile photo. Your email address and role can only be changed by an Admin. If either needs updating, contact your Admin directly.

Changing Your Password

Navigate to My Profile → Security → Change Password. You must enter your current password to set a new one. Passwords cannot be reused (last 12 passwords are checked).

Managing MFA

To change your authenticator device (e.g. after getting a new phone), go to My Profile → Security → Multi-Factor Authentication. Click Re-enrol and authenticate with your existing device or one of your backup recovery codes. You will be shown a new QR code to scan with your new device.

Active Sessions

The Sessions tab under Security shows all active login sessions with device type, IP address, and last seen time. If you spot an unrecognised session, click Revoke next to it to force sign-out of that device. Click Revoke All Other Sessions to sign out everywhere except your current browser.

KYC-Agent exposes a versioned REST API at https://api.kyc-agent.com/v1/ and a GraphQL endpoint at /graphql. All requests must be authenticated with an API key. The API follows OpenAPI 3.1 and interactive documentation is available at /docs.

Key Types & Scopes

API keys are scoped to the minimum required permissions. Keys are created by users with the Admin role or above.

Generating an API Key

Navigate to Settings → API Keys → New Key. Assign a descriptive name (e.g. CRM Integration – Production), select the key type, set an optional expiry date, and click Generate. The full secret is shown once only. Copy it immediately and store it in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, etc.).

Authenticating API Requests

Pass the key as a Bearer token in the Authorization header on every request:

Authorization: Bearer kyca_live_3Xm9pQ7rLtY2hNwKvB4cAjZsdFgH
Content-Type: application/json
X-Tenant-ID: acme-fs

Rate Limits & Headers

Every API response includes rate-limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 947
X-RateLimit-Reset: 1745280060
Retry-After: 53  // present only when 429 is returned

Default limits: Live keys — 1,000 RPM. Bulk keys — 10,000 RPM. If you exceed the limit, the API returns 429 Too Many Requests. Back off exponentially and retry after Retry-After seconds.

Standard Error Format

All API errors follow a consistent JSON envelope:

{
  "error": {
    "code": "DOCUMENT_QUALITY_INSUFFICIENT",
    "message": "The uploaded identity document failed minimum DPI requirements.",
    "details": {
      "field": "documents[0]",
      "reason": "estimated_dpi=142, minimum_required=300"
    },
    "request_id": "req_01HXYZ4K5NABCDEF12345678"
  }
}

Always log the request_id — support engineers use it to trace any request in the audit log.

The primary verification endpoint accepts either a synchronous or asynchronous call mode. For real-time onboarding flows, use mode: "sync". For background processing, use mode: "async" and receive results via webhook.

Individual Verification Request

POST to /v1/verifications with a JSON body. Documents are Base64-encoded or provided as signed upload URLs:

{
  "entity_type": "individual",
  "mode": "sync",
  "rule_set_id": "rule_standard_kyc_v3",
  "external_ref": "customer_88821",
  "subject": {
    "first_name": "Jane",
    "last_name": "Thornton",
    "date_of_birth": "1988-04-15",
    "nationality": "GB"
  },
  "documents": [
    {
      "type": "passport",
      "country": "GB",
      "images": [
        { "side": "front", "url": "https://uploads.kyc-agent.com/doc/signed/abc123" }
      ]
    }
  ],
  "biometrics": {
    "liveness_session_id": "lv_01HXYZ88K9P..."
  }
}

Synchronous Response

In sync mode, the API returns the full verification result within the same HTTP response (typically 5–30 seconds):

{
  "id": "ver_01HYABCDE12345",
  "status": "review_required",
  "risk_score": 42,
  "risk_band": "medium",
  "external_ref": "customer_88821",
  "checks": {
    "document_authenticity": { "status": "pass", "score": 0.98 },
    "face_match": { "status": "pass", "score": 0.99 },
    "sanctions": { "status": "pass", "hits": [] },
    "pep": { "status": "review", "hits": [{ "name": "Jane Thornton", "category": "pep_tier_2", "confidence": 0.61 }] },
    "adverse_media": { "status": "pass", "articles_reviewed": 312 }
  },
  "created_at": "2026-04-21T09:14:33Z",
  "completed_at": "2026-04-21T09:14:57Z"
}

Use bulk endpoints to screen entire portfolios without individual API calls per entity. Bulk processing is ideal for overnight rescreening, onboarding portfolio migrations, and periodic review runs.

CSV Format Specification

Prepare a UTF-8 encoded CSV file with the following header row. Columns marked with * are required:

external_ref*,entity_type*,full_name*,date_of_birth,nationality,jurisdiction,rule_set_id
cust_001,individual,Alice Bergmann,1991-07-22,DE,DE,rule_standard_kyc_v3
cust_002,individual,Marco Ferretti,1985-12-03,IT,IT,rule_standard_kyc_v3
org_003,business,Zenith Capital Ltd,,,,rule_kyb_standard_v2

Submitting a Batch

POST the CSV as a multipart/form-data upload to /v1/verifications/bulk:

curl -X POST https://api.kyc-agent.com/v1/verifications/bulk \
  -H "Authorization: Bearer kyca_bulk_xxxx" \
  -H "X-Tenant-ID: acme-fs" \
  -F "file=@portfolio_q2_2026.csv" \
  -F "notify_webhook=https://hooks.acme.com/kyc-results"

The response includes a batch_id for status polling:

{
  "batch_id": "bat_01HYABCDE67890",
  "status": "queued",
  "row_count": 3847,
  "estimated_completion_seconds": 420
}

Polling Batch Status

Poll GET /v1/verifications/bulk/{batch_id}/status until status is completed or failed:

{
  "batch_id": "bat_01HYABCDE67890",
  "status": "completed",
  "progress": { "processed": 3847, "total": 3847 },
  "summary": {
    "approved": 3541,
    "review_required": 278,
    "rejected": 28
  },
  "results_url": "https://exports.kyc-agent.com/batch/bat_01HYABCDE67890/results.csv?sig=...",
  "expires_at": "2026-04-22T09:00:00Z"
}

Rule sets are the heart of KYC-Agent's flexibility. They define exactly which checks run, in which order, with what parameters, and what the platform should do at each risk level. Rule sets are JSON documents deployed via the API or the Admin UI.

Rule Set JSON Structure

A complete rule set has four top-level sections: meta, checks, scoring, and routing:

{
  "id": "rule_standard_kyc_v3",
  "name": "Standard KYC — Individual",
  "entity_types": ["individual"],
  "checks": [
    { "id": "document_authenticity", "required": true },
    { "id": "face_match",            "required": true, "min_score": 0.97 },
    { "id": "sanctions",            "required": true, "lists": ["ofac_sdn", "eu_consolidated", "un_sc", "hm_treasury"] },
    { "id": "pep",                 "required": true },
    { "id": "adverse_media",        "required": false,
      "condition": { "if_pep_hit": true }
    }
  ],
  "scoring": {
    "weights": {
      "document_authenticity": 0.25,
      "face_match":            0.20,
      "sanctions":            0.35,
      "pep":                 0.15,
      "adverse_media":        0.05
    }
  },
  "routing": {
    "auto_approve_below": 30,
    "auto_escalate_above": 70,
    "on_sanctions_hit": "reject_and_alert",
    "on_pep_hit": "escalate_to_compliance_officer"
  }
}

Conditional Check Execution

The condition field on any check allows you to skip or include it based on prior check results. This reduces unnecessary API calls to third-party data providers for clearly clean entities, cutting both cost and processing time:

• "condition": { "if_pep_hit": true } — only run adverse media if PEP check flagged a hit
• "condition": { "if_risk_score_above": 40 } — only run extended checks if the running score is elevated
• "condition": { "if_jurisdiction": ["IR", "KP", "SY"] } — always run EDD for high-risk jurisdictions

Deploying a Rule Set via API

curl -X PUT https://api.kyc-agent.com/v1/rule-sets/rule_standard_kyc_v3 \
  -H "Authorization: Bearer kyca_live_xxxx" \
  -H "Content-Type: application/json" \
  -d @rule_standard_kyc_v3.json

Perpetual KYC (pKYC) replaces periodic manual re-review with continuous event-driven re-assessment. Once an entity is enrolled in monitoring, KYC-Agent automatically re-runs the relevant checks whenever a list is updated, a news event fires, or the periodic review schedule triggers.

Enrolling an Entity in Monitoring

POST to /v1/monitoring/enroll after the initial verification completes:

{
  "verification_id": "ver_01HYABCDE12345",
  "schedule": {
    "type": "risk_tiered",
    "low_risk_interval_days": 365,
    "medium_risk_interval_days": 90,
    "high_risk_interval_days": 30
  },
  "triggers": [
    "sanctions_list_update",
    "adverse_media_spike",
    "pep_status_change"
  ],
  "alert_webhook": "https://hooks.acme.com/monitoring-alerts"
}

Monitoring Alert Webhook Payload

When a monitoring event fires, KYC-Agent delivers a structured payload to your registered webhook:

{
  "event": "monitoring.alert.fired",
  "event_id": "evt_01HZMONABC12345",
  "fired_at": "2026-04-21T14:22:11Z",
  "entity": {
    "verification_id": "ver_01HYABCDE12345",
    "external_ref": "customer_88821",
    "name": "Jane Thornton"
  },
  "trigger": "sanctions_list_update",
  "alert": {
    "severity": "critical",
    "list": "ofac_sdn",
    "match_confidence": 0.94,
    "match_details": { "name": "Jane Thornton", "dob": "1988-04-15" }
  },
  "case_id": "cas_01HZMONCAS67890",
  "case_url": "https://app.kyc-agent.com/cases/cas_01HZMONCAS67890"
}

The Reports module provides pre-built compliance dashboards and a custom report builder. All reports are accessible both in the UI and via the API.

Built-In Report Types

Pulling Reports via API

curl https://api.kyc-agent.com/v1/reports/verification-volume \
  -H "Authorization: Bearer kyca_ro_xxxx" \
  -G \
  --data-urlencode "period=2026-04" \
  --data-urlencode "group_by=day" \
  --data-urlencode "format=json"

Audit-Ready Exports

All exported reports are signed with a PKCS#7 digital signature and include a SHA-256 integrity hash. Regulators can verify the report has not been tampered with using the public verification key published at https://trust.kyc-agent.com/public-key. Exports are available in PDF (human-readable), CSV (tabular data), and JSON (machine-readable).

Scheduling Automated Reports

Use POST /v1/reports/schedules to configure automatic report generation and delivery. Reports can be emailed to a distribution list or deposited in an S3/Azure Blob Storage bucket via pre-configured credentials.

Webhooks allow KYC-Agent to push events to your infrastructure in real time rather than requiring polling. Register one endpoint per integration concern for clean separation of concerns.

Registering a Webhook Endpoint

{
  "url": "https://hooks.acme.com/kyc-agent",
  "events": [
    "verification.completed",
    "sanctions.hit",
    "case.escalated",
    "risk_score.changed"
  ],
  "secret": "whsec_your_signing_secret_here",
  "active": true
}

Webhook Payload Structure

All events share the same envelope structure. The data field is specific to each event type:

{
  "event": "verification.completed",
  "event_id": "evt_01HZWEBOOK12345",
  "api_version": "2026-04-01",
  "created_at": "2026-04-21T09:15:01Z",
  "tenant_id": "acme-fs",
  "data": {
    "verification_id": "ver_01HYABCDE12345",
    "external_ref": "customer_88821",
    "status": "review_required",
    "risk_score": 42,
    "risk_band": "medium"
  }
}

Verifying the HMAC Signature (Python)

Each delivery includes an X-KYC-Signature header containing a HMAC-SHA256 signature of the raw request body. Always verify this before processing the payload:

import hmac, hashlib
from flask import request, abort

WEBHOOK_SECRET = b"whsec_your_signing_secret_here"

def verify_signature(payload_bytes, signature_header):
    expected = hmac.new(
        WEBHOOK_SECRET, payload_bytes, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, signature_header):
        abort(400, "Invalid signature")

@app.route("/webhooks/kyc-agent", methods=["POST"])
def receive_webhook():
    verify_signature(
        request.get_data(),
        request.headers.get("X-KYC-Signature", "")
    )
    event = request.json
    # process event["event"] safely here
    return "", 200

Event Catalog

Native Connectors

Pre-built connectors are available for Salesforce (CRM sync), HubSpot, Snowflake, Databricks, Splunk SIEM, and Microsoft Sentinel. Each is configured via the Connector Wizard at Admin → Integrations → Connectors in under five minutes — no custom code required.

API key permissions mirror the platform's RBAC model. The table below maps key types to the operations they authorise. Service accounts (non-human integrations) should use the minimum-privilege key type for their use case.

API Operations by Key Type

Service Account Best Practices

• Create one API key per integration, not per developer — keys are shared at the integration level
• Rotate keys on a schedule (90 days recommended) using the 15-minute overlap window for zero-downtime rotation
• Store keys in a secrets manager — never in source code, config files, or environment variables committed to version control
• Set an expiry date on all keys; prefer short-lived keys (30 days) for automated CI/CD pipeline integrations
• Review the API access log in Admin → API Keys → Usage monthly to detect unusual call patterns

Every organisation runs inside an isolated tenant. Each tenant has its own data store, rule engine, API keys, audit log, and user directory. No data can cross tenant boundaries — isolation is enforced at both the application and database layers.

Creating a Tenant

From the Super Admin console, navigate to Tenants → New Tenant and complete the provisioning form:

1. Organisation name & slug

   The slug becomes the unique tenant identifier used in API headers and URLs (e.g. acme-fs). Choose carefully — it cannot be changed after provisioning.

2. Legal jurisdiction

   Select the primary regulatory jurisdiction (e.g. GB, EU, US). This pre-populates the default rule set with the correct watchlists and regulatory thresholds for that region.

3. Data residency region

   Choose where your data is physically stored: eu-west-1 (Ireland), us-east-1 (Virginia), or ap-southeast-1 (Singapore). This decision is governed by your data processing agreements and cannot be changed without a full migration.

4. Primary contact email

   This address receives system alerts, SLA breach notifications, and billing communications. Use a distribution list rather than an individual's address.

5. Click Provision

   Provisioning takes up to 60 seconds. The system creates the database schema, seeds default rule sets, and sends a welcome email to the primary contact.

Core Tenant Settings

After provisioning, navigate to Settings → General and configure these essential options before inviting users:

Roles control what users can see and do. Assign roles following the principle of least privilege — users should only access what they need to complete their work. Roles can be changed at any time by an Admin.

Available Roles

Inviting Users

1. Navigate to Users → Invite

   Enter the user's work email address and select their role from the dropdown.

2. Send the invitation

   Click Send Invitation. The user receives a one-time setup link valid for 72 hours. If the link expires, click Resend from the Users list.

3. User completes setup

   The user sets a password and enrolls MFA. Their account becomes active immediately after setup. They will appear as Active in the Users list.

Enforcing MFA Organisation-Wide

Navigate to Settings → Security → MFA Policy and toggle Require MFA for all users. Once enabled, any user without MFA configured will be forced to enroll at their next login before accessing any platform function. Supported MFA methods: TOTP (authenticator app), SMS (backup only), and hardware security keys (FIDO2/WebAuthn).

Deactivating & Offboarding Users

When a user leaves the organisation, deactivate their account immediately rather than deleting it. Deactivated accounts retain their full audit trail — all past actions remain attributable. To deactivate: go to Users → [user name] → Deactivate. Deactivated users cannot log in and are not billed, but their data and audit history are preserved. If SSO is configured, also revoke the session in your identity provider to prevent token replay.

The rule engine defines which checks run on a verification, how results are scored, and what happens at each risk level. Every verification references a named rule set. KYC-Agent ships with standard rule sets for common jurisdictions — you can use these as-is or clone and customise them.

Viewing Default Rule Sets

Navigate to Settings → Rule Sets. The list shows all available rule sets for your tenant. Each entry shows its ID, description, entity types it covers, and the last date it was modified. Pre-built rule sets are prefixed rule_system_ and are read-only. Clone one to create a custom variant.

Adjusting Risk Thresholds

Click Edit on a rule set and navigate to the Routing tab. Adjust the three score bands to match your organisation's risk appetite:

Conservative deployments (financial services, regulated markets) typically set auto-approve below 25 and escalate above 60. Retail deployments with lower-risk populations can widen the auto-approve band up to 40.

SLA Timers

Under Settings → SLA, set maximum processing times per risk tier. When a case in the manual-review queue exceeds its SLA, an escalation notification is sent to Compliance Officers and Admins. Typical values:

• Low risk (score 0–30 routed for spot-check): 48 hours
• Medium risk (31–69): 8 hours
• High risk (70–100): 2 hours

SLA timers pause automatically during configured out-of-hours windows (e.g. weekends) if your jurisdiction permits. Configure these under Settings → SLA → Business Hours.

API keys allow external systems and integrations to interact with KYC-Agent programmatically. Each key has a type that scopes its permissions, an optional expiry date, and an IP allowlist.

Creating Your First API Key

1. Navigate to Settings → API Keys → New Key

   Give the key a descriptive name that identifies its purpose and owning system (e.g. Onboarding Portal — Production).

2. Select the key type

   Choose the minimum-privilege type for the integration's needs. See the key types table below.

3. Set an expiry date (recommended)

   Keys without an expiry are valid indefinitely. For production integrations, set a 90-day expiry and schedule a rotation reminder.

4. Copy the key immediately

   The full key value is shown only once at creation. Copy it into your secrets manager now. If you lose the key, you must revoke it and create a new one.

API Key Types

Storing Keys Securely

Never store API keys in source code, config files, or environment variables committed to version control. Use a secrets manager:

• AWS: AWS Secrets Manager or Parameter Store (SecureString)
• Azure: Azure Key Vault with Managed Identity access
• GCP: Secret Manager with Workload Identity
• Self-hosted: HashiCorp Vault with AppRole authentication

Every action taken by users, automated agents, and API callers is recorded in the immutable audit log. The log is write-once — no action can be edited or deleted. It is your primary evidence trail for regulatory inspections and internal investigations.

Accessing the Audit Log

Navigate to Admin → Audit Log. The default view shows the last 24 hours of activity across all users and integrations. Use the filter bar to narrow results:

• User: filter to a specific user's actions
• Action type: e.g. verification.submitted, case.approved, user.deactivated, rule_set.updated
• Resource: filter to actions on a specific case, entity, or rule set by ID
• Date range: supports up to 90-day windows in the UI; older data is available via API or export

Exporting Audit Logs

Click Export in the top-right of the Audit Log view. Choose your format:

• JSON: machine-readable, preserves full metadata structure — recommended for SIEM import
• CSV: flat tabular format — recommended for spreadsheet review and regulator submissions

Large exports (over 100,000 rows) are processed asynchronously. You will receive an email with a signed download link when the export is ready. Download links expire after 24 hours.

Retention Policy

Logs are retained for 7 years by default, configurable up to 10 years. Retention cannot be shortened without Super Admin approval and a documented compliance justification. To review or change the retention setting: Settings → Compliance → Audit Log Retention.

The Admin Health Dashboard gives you a real-time view of system status, integration health, processing queue depths, and SLA performance.

Health Dashboard

Access via Admin → System Health. Each sub-system is shown as a coloured status indicator:

Amber and red status indicators are clickable — each links directly to the affected service's recent log entries and any open incident tickets.

Alert Notifications

Configure who receives operational alerts under Admin → Notifications → Admin Alerts. Available notification channels:

• Email: distribution list for SLA breaches, system degradation, and security events
• Slack: post alerts to a designated compliance or ops channel via webhook
• PagerDuty: escalate critical alerts for on-call response
• Microsoft Teams: adaptive card notifications to a designated Teams channel

Verification Queue Depth

The queue depth widget on the Health Dashboard shows the number of pending verifications in each processing state. A persistently growing queue may indicate a data provider latency issue or an under-provisioned worker tier. If the queue depth exceeds your SLA capacity, contact support to temporarily scale the worker tier.

KYC-Agent's multi-tenant model provides complete data isolation between customer organisations. Each tenant is logically equivalent to a fully independent deployment — the separation happens at every layer of the stack: authentication, application routing, database storage, and background processing.

Isolation Model

The platform uses schema-per-tenant database isolation. Each tenant's data lives in a dedicated PostgreSQL schema with row-level security (RLS) policies that cryptographically prevent cross-tenant queries. The application layer adds a second isolation fence: the tenant_id claim embedded in every JWT is verified on every request before any database query executes.

Automated Tenant Provisioning via API

Use the Admin API to provision tenants programmatically — useful for ISV partners and managed service providers that need to spin up hundreds of tenant instances on demand:

{
  "name": "Acme Financial Services",
  "slug": "acme-fs",
  "jurisdiction": "GB",
  "data_region": "eu-west-1",
  "plan": "enterprise",
  "contact_email": "compliance@acme.com",
  "seed_rule_sets": ["rule_system_kyc_gb_v4", "rule_system_kyb_gb_v2"],
  "feature_flags": {
    "perpetual_kyc": true,
    "edd_packaging": true,
    "hitl_escalation": true
  }
}

The response includes the provisioning job ID. Poll GET /admin/v1/tenants/{slug}/status until status is active (typically 30–60 seconds). Once active, the tenant's first Admin user can be invited via the POST /admin/v1/tenants/{slug}/invites endpoint.

Testing Isolation

After provisioning multiple tenants, verify isolation by attempting a cross-tenant API call. Use Tenant A's valid JWT with Tenant B's slug in the X-Tenant-ID header. The platform should return 403 Forbidden with error code TENANT_ID_MISMATCH. Any other response indicates a misconfiguration that must be investigated before going live.

The rule engine is a declarative JSON DSL. A rule set specifies checks (which verifications to run), scoring weights (how to combine check results into a risk score), conditions (when to skip or add checks dynamically), and routing (what action to take at each score band).

Full Rule Set JSON Schema

A production rule set covering individual KYC with conditional Enhanced Due Diligence:

{
  "id": "rule_kyc_gb_v4",
  "name": "Standard KYC — UK Individual",
  "version": "4.0.1",
  "entity_types": ["individual"],
  "checks": [
    {
      "id": "document_authenticity",
      "required": true,
      "provider": "onfido"
    },
    {
      "id": "face_match",
      "required": true,
      "provider": "onfido",
      "params": { "min_confidence": 0.97 }
    },
    {
      "id": "sanctions",
      "required": true,
      "params": {
        "lists": ["ofac_sdn", "eu_consolidated", "un_sc", "hm_treasury"],
        "fuzzy_threshold": 0.85
      }
    },
    {
      "id": "pep",
      "required": true,
      "params": { "tiers": [1, 2, 3] }
    },
    {
      "id": "adverse_media",
      "required": false,
      "condition": {
        "any_of": [
          { "check": "pep", "result": "hit" },
          { "risk_score_above": 50 }
        ]
      }
    },
    {
      "id": "enhanced_due_diligence",
      "required": false,
      "condition": {
        "all_of": [
          { "check": "pep", "result": "hit" },
          { "jurisdiction_in": ["IR", "KP", "SY", "RU"] }
        ]
      }
    }
  ],
  "scoring": {
    "model": "weighted_sum",
    "weights": {
      "document_authenticity": 0.20,
      "face_match":            0.15,
      "sanctions":            0.40,
      "pep":                 0.20,
      "adverse_media":        0.05
    },
    "overrides": {
      "on_sanctions_confirmed": 100
    }
  },
  "routing": {
    "auto_approve_below": 30,
    "manual_review_range": [30, 69],
    "auto_escalate_above": 70,
    "on_sanctions_hit": "reject_and_alert",
    "on_pep_hit": "escalate_to_compliance_officer",
    "on_edd_triggered": "assign_to_senior_officer"
  }
}

Conditional Check Execution

The condition field supports three combinators: any_of (OR logic), all_of (AND logic), and none_of (NOT logic). Conditions can test prior check results, jurisdiction codes, running risk scores, and entity attributes such as entity_type or nationality. This lets you build nuanced risk-proportionate workflows:

• Only run adverse_media if PEP check returns a hit (saves cost on clean entities)
• Always run enhanced_due_diligence for high-risk jurisdictions regardless of score
• Skip face_match for corporate entities where biometrics are not applicable

Calibrating Scoring Weights

Weights must sum to 1.0 across all checks for a given entity type. The scoring model computes a weighted average of per-check failure probabilities, multiplied by 100 to produce the final risk score (0–100). Use the overrides section to hard-set the score to 100 on specific deterministic outcomes (e.g. a confirmed sanctions hit should always score 100, regardless of other checks).

Rule Set Versioning & Promotion

Rule sets are versioned using semantic versioning. Each deployment creates an immutable snapshot. When you save changes, the current version is archived and a new version is created. The active version can be pinned per-verification by passing a rule_set_version parameter in the API request. To promote a tested rule set from sandbox to production:

# Export from sandbox tenant
curl https://api.kyc-agent.com/v1/rule-sets/rule_kyc_gb_v4 \
  -H "Authorization: Bearer kyca_test_xxxx" \
  -H "X-Tenant-ID: acme-sandbox" \
  -o rule_kyc_gb_v4.json

# Import to production tenant
curl -X PUT https://api.kyc-agent.com/v1/rule-sets/rule_kyc_gb_v4 \
  -H "Authorization: Bearer kyca_live_xxxx" \
  -H "X-Tenant-ID: acme-fs" \
  -H "Content-Type: application/json" \
  -d @rule_kyc_gb_v4.json

For enterprise deployments, API key management requires a formal governance strategy to prevent key sprawl, ensure timely rotation, and maintain a clear audit trail of which systems accessed the platform and when.

Key Scopes & Permissions

Every key is scoped to a specific set of endpoints and HTTP methods. A read-only reporting key cannot submit verifications even if the secret is compromised. Always create keys with the minimum scope required for their purpose:

Zero-Downtime Key Rotation

Schedule automatic key rotation under Settings → API Keys → [key name] → Rotation Policy. The platform supports a configurable overlap window (5–60 minutes, default 15 minutes) during which both the old and new keys are simultaneously valid. This allows your systems to fetch the new key from your secrets manager and update their configuration without a service interruption:

{
  "overlap_minutes": 15,
  "notify_webhook": "https://hooks.acme.com/key-rotations",
  "store_in_vault": {
    "provider": "aws_secrets_manager",
    "secret_arn": "arn:aws:secretsmanager:eu-west-1:123456789:secret:kyca-prod-key"
  }
}

When the vault integration is configured, the new key value is automatically written to your secrets manager vault immediately after generation — your application simply needs to reload credentials from the vault at its next startup or secrets-refresh cycle.

IP Allowlisting

Restrict key usage to specific source IP addresses or CIDR ranges under Settings → API Keys → [key name] → IP Allowlist. Any API call from an IP outside the allowlist returns 403 Forbidden with error code IP_NOT_ALLOWED. Use this to limit production keys to your data centre egress IPs or cloud NAT gateway addresses. Allowlists do not apply to sandbox keys.

Key Usage Monitoring

The API access log at Admin → API Keys → [key name] → Usage shows every API call made with a key: timestamp, endpoint, HTTP method, response code, and source IP. Review this log monthly for anomalous patterns — unexpected endpoints, unusual call volumes, or calls from unrecognised IPs. Set up an automated alert via Admin → Notifications → API Anomaly Alerts to be notified of volume spikes or unexpected 4xx/5xx error rates.

The audit log provides an immutable, tamper-evident record of every action taken by users, automated agents, and API callers across all tenants. For regulated industries, the audit log is your primary regulatory compliance artefact.

Log Entry Structure

Each audit log entry is a structured JSON object with a cryptographic chain linking it to the previous entry — making post-hoc insertion or deletion detectable. A representative log entry:

{
  "id": "log_01HZAUDIT12345",
  "sequence": 1847293,
  "prev_hash": "sha256:a3f8b2c1...",
  "timestamp": "2026-04-21T14:22:11.447Z",
  "tenant_id": "acme-fs",
  "actor": {
    "type": "user",
    "id": "usr_01HXUSR88321",
    "email": "sarah.chen@acme.com",
    "role": "compliance_officer",
    "ip_address": "203.0.113.42",
    "session_id": "sess_01HXSESS4412"
  },
  "action": "case.approved",
  "resource": {
    "type": "case",
    "id": "cas_01HZCASE77891"
  },
  "context": {
    "risk_score_at_decision": 42,
    "decision_rationale": "PEP tier 2 hit reviewed. Subject confirmed as retired local official. Risk accepted.",
    "override_automated_decision": false
  },
  "entry_hash": "sha256:9c4e1f7d..."
}

Log Retention & Immutability

Logs are retained for 7 years by default (configurable up to 10 years). The platform enforces immutability at the storage tier using object-lock policies on the underlying object store. No administrative action — including Super Admin commands — can modify or delete log entries. Retention cannot be shortened without a formally documented compliance justification approved by Hayden-Fisher Technologies, Inc.

SIEM Integration

Stream audit logs in real time to your Security Information and Event Management (SIEM) platform. KYC-Agent supports three integration methods:

1. Native push connectors (recommended)

   Configure under Admin → Integrations → SIEM. Supported platforms: Splunk (HTTP Event Collector), Microsoft Sentinel (Log Analytics workspace), Elastic SIEM (Elasticsearch ingest endpoint), and IBM QRadar (LEEF format over syslog TLS). Events are streamed with sub-5-second latency.

2. S3/Azure Blob/GCS export sink

   Configure a cloud storage bucket as an export sink. Log files are written in newline-delimited JSON (NDJSON) format, partitioned by date and tenant, and rotated hourly. Your SIEM can ingest files directly from the bucket. Suitable for SIEM platforms that natively support S3 or blob storage ingestion.

3. Audit log pull API

   Poll GET /admin/v1/audit-log/stream?since={cursor} using a cursor-based pagination model. Each response returns up to 1,000 entries and a next_cursor for the subsequent page. Suitable for custom SIEM ingestion pipelines where push is not possible.

Export Formats

Beyond the built-in technical isolation, enterprise deployments benefit from additional governance patterns to strengthen tenant isolation in practice.

Per-Tenant Rule Sets

System-level rule sets apply across all tenants for the same base configuration. However, enterprise tenants often need jurisdiction-specific or customer-segment-specific variations. Create tenant-scoped rule sets (prefixed with your tenant slug, e.g. acme-fs_rule_kyc_premium_v1) that are only visible and usable within your tenant. These override system defaults for verifications that reference them.

Data Residency Enforcement

For tenants with strict data sovereignty requirements (e.g. GDPR Art. 44 restrictions, PDPA Thailand, or PIPL China), the platform enforces data residency at two levels:

• Storage: All documents, PII fields, and raw verification data are stored exclusively in the tenant's configured region. Cross-region replication is disabled by default.
• Processing: Verification jobs execute on worker nodes physically located in the tenant's region. Third-party provider API calls are routed through regional endpoints where the provider supports it.

To verify your current data residency configuration: Settings → Compliance → Data Residency. A region-lock badge confirms the active enforcement state.

Tenant Backup & Disaster Recovery

Each tenant's data is backed up continuously (point-in-time recovery via WAL streaming) with full snapshots every 6 hours. Backups are stored in the same region as the primary data. Recovery Point Objective (RPO): <1 minute. Recovery Time Objective (RTO): <4 hours. Test your recovery capability annually by requesting a sandbox restore from a specific point-in-time via support.

Tenant Offboarding

When a tenant relationship ends, the offboarding process follows a regulated data destruction protocol:

1. Request export package

   Before offboarding, request a full data export in your required format. Exports include all entity records, verification results, case history, and audit logs in structured JSON, zipped and signed.

2. Verify export completeness

   Confirm the row counts and checksum manifest before acknowledging receipt. Once offboarding is confirmed, data deletion is irreversible.

3. Initiate data deletion

   Super Admin initiates the deletion workflow. Data is cryptographically shredded (key destruction for encrypted volumes) within 30 days. A Certificate of Destruction is issued for your compliance records.

Webhooks allow KYC-Agent to push events to your infrastructure in real time rather than requiring your systems to poll for changes. Designing your integration around webhooks produces lower latency, lower API cost, and simpler application logic.

Registering Webhook Endpoints

Register one endpoint per integration concern for clean separation of responsibilities. For example: one endpoint for your onboarding service that handles verification.completed events, and a separate endpoint for your compliance dashboard that handles sanctions.hit and case.escalated events.

{
  "name": "Onboarding Service",
  "url": "https://api.acme.com/webhooks/kyc-onboarding",
  "events": [
    "verification.completed",
    "verification.failed"
  ],
  "active": true,
  "api_version": "2026-04-01"
}

The response includes the endpoint's signing_secret — shown only once at creation. Store it in your secrets manager and use it to verify the HMAC signature on every incoming delivery.

Verifying HMAC Signatures

Every delivery includes an X-KYC-Signature header containing t={timestamp},v1={hmac_sha256_hex}. The HMAC is computed over the concatenation of the timestamp and raw request body. Always verify before processing to prevent replay attacks and forged payloads:

import hmac, hashlib, time
from fastapi import Request, HTTPException

WEBHOOK_SECRET = b"whsec_your_signing_secret_here"
TOLERANCE_SECONDS = 300  # reject events older than 5 minutes

async def verify_kyc_signature(request: Request):
    sig_header = request.headers.get("X-KYC-Signature", "")
    parts = dict(p.split("=", 1) for p in sig_header.split(","))
    ts, v1 = parts.get("t"), parts.get("v1")
    if not ts or not v1:
        raise HTTPException(400, "Missing signature")
    if abs(time.time() - int(ts)) > TOLERANCE_SECONDS:
        raise HTTPException(400, "Timestamp too old — possible replay")
    body = await request.body()
    expected = hmac.new(
        WEBHOOK_SECRET,
        f"{ts}.".encode() + body,
        hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, v1):
        raise HTTPException(400, "Invalid signature")

@app.post("/webhooks/kyc-onboarding")
async def receive_onboarding_event(request: Request):
    await verify_kyc_signature(request)
    event = await request.json()
    # deduplicate using event["event_id"]
    # process event["event"] safely here
    return {"status": "ok"}

Retry & Idempotency

Failed webhook deliveries (non-2xx responses or connection timeouts within 10 seconds) are retried with exponential backoff: 5 s → 30 s → 5 min → 30 min → 2 h → 8 h → 24 h. After the final retry (24 hours from first delivery attempt), the event is marked as permanently failed and appears in the Admin → Integrations → Dead Letters queue for manual replay. Build idempotency into your endpoint by storing processed event_id values and checking for duplicates before processing:

import redis

r = redis.Redis.from_url(REDIS_URL)

def is_duplicate_event(event_id: str) -> bool:
    # SET NX with 48h TTL — returns False if key was newly set (not a duplicate)
    return not r.set(f"kyc:event:{event_id}", 1, nx=True, ex=172800)

if is_duplicate_event(event["event_id"]):
    return {"status": "duplicate_ignored"}
# process event safely ...

Complete Event Catalog

Native Pre-Built Connectors

For popular platforms, use the Connector Wizard at Admin → Integrations → Connectors:

• Salesforce: Sync verification results and risk scores to Contact and Account records automatically
• HubSpot: Update contact properties with KYC status and risk tier for deal pipeline automation
• Snowflake / Databricks: Stream all verification events to your data warehouse for ML and analytics
• n8n / Zapier: No-code workflow automation — trigger any downstream action on KYC events
• Splunk / Microsoft Sentinel / Elastic SIEM: Real-time audit log streaming for security monitoring

Single Sign-On (SSO) centralises authentication through your corporate Identity Provider (IdP) — Okta, Microsoft Entra ID (Azure AD), Google Workspace, PingFederate, or any SAML 2.0 / OIDC-compatible provider. Once SSO is configured, users authenticate through the IdP and are provisioned or deprovisioned automatically via SCIM 2.0.

SAML 2.0 Configuration

Navigate to Settings → Security → SSO → Add Provider → SAML 2.0. Provide the values shown below — the exact labels in your IdP will vary but the concepts are universal:

<!-- Values to enter in your IdP -->
ACS URL:      https://app.kyc-agent.com/sso/saml/acs/{tenant_slug}
Entity ID:    https://app.kyc-agent.com/sso/saml/metadata/{tenant_slug}
NameID:       email (persistent)

<!-- Required SAML attributes from IdP -->
email:        user.email
first_name:   user.firstName
last_name:    user.lastName
role:         kyc_agent.role  <!-- maps IdP group to KYC-Agent role -->

Configure role mapping under the Attribute Mappings tab. Map IdP group names (e.g. KYC_Analyst, KYC_Compliance) to KYC-Agent roles (analyst, compliance_officer). Users in unmapped groups are assigned the viewer role by default.

SCIM 2.0 Automated Provisioning

Enable SCIM at Settings → Security → SSO → SCIM Provisioning. Copy the SCIM endpoint URL and bearer token into your IdP. Once active, users created, updated, or deactivated in your IdP are reflected in KYC-Agent within seconds — no manual invitations required. Group membership changes in the IdP automatically update user roles in KYC-Agent.

For deployments processing more than 10,000 verifications per day, additional configuration is recommended to maintain SLA performance and control third-party data provider costs.

Worker Concurrency

The worker_concurrency parameter controls how many parallel verification workflows run simultaneously on a single worker node. The default is 4 concurrent workflows per worker. Increase this value cautiously — each concurrency slot consumes database connections and makes outbound API calls to third-party providers that may have their own rate limits:

{
  "worker_concurrency": 8,
  "worker_instances": 4,
  "max_queue_depth_before_scale": 200,
  "provider_rate_limits": {
    "onfido": 40,
    "refinitiv_sanctions": 30,
    "lexisnexis_pep": 20
  }
}

Data Provider Response Caching

Enable response caching for sanctions and PEP data providers under Settings → Performance → Provider Caching. Cached responses reduce both cost and latency for repeat screenings of the same entity. Configure TTL values that balance data freshness against call volume:

Horizontal Auto-Scaling

In Kubernetes deployments, a HorizontalPodAutoscaler scales the worker tier based on Celery queue depth (exposed as a custom metric via the Prometheus exporter). The target queue depth threshold is configurable — a typical starting point is to add one worker replica for every 100 queued verifications above the baseline. This keeps average processing latency below your SLA threshold even during onboarding spikes.

Provider Fallback Configuration

Configure provider fallback chains under Settings → Providers → Fallback. If the primary sanctions provider is unavailable (returns 5xx or times out after the configured threshold), the rule engine automatically falls back to the secondary provider without failing the verification. This eliminates hard dependencies on single data providers and improves SLA resilience. Alert thresholds can be set to notify Admins when fallback is activated.

A fintech platform verifies a new user's identity in seconds using document upload and selfie matching.

Scenario

A user signs up to a digital payment wallet. Before they can send money, the platform must confirm their legal identity matches their declared details.

Walkthrough

1. User uploads passport photo

   The platform presents an upload prompt. The user photographs their passport via the mobile camera.

2. OCR extracts MRZ data

   KYC-Agent reads the Machine Readable Zone and cross-checks against the visual zone.

3. Liveness check

   The user completes a brief face-capture sequence. Anti-spoofing AI rejects deepfakes and printed photos.

4. Biometric comparison

   Face on document vs. live selfie — match score above 97% required to auto-pass.

5. Result returned

   Verification status (Pass/Review/Fail) is returned within 8 seconds via webhook and API response.

A B2B marketplace validates a vendor's registration, directors, and legal status automatically.

Scenario

A new supplier wants to list products on a procurement platform. Before approval, the platform verifies the business is legitimately registered, active, and that its directors pass identity checks.

Walkthrough

1. Submit company registration number

   The platform sends the registration number and country code to the KYB API endpoint.

2. Registry lookup

   KYC-Agent queries the relevant national corporate registry in real time.

3. Director verification

   Each listed director is automatically cross-referenced against sanctions and PEP lists.

4. Status determination

   Combined result: business active + directors clean → Approved. Any flag → Review.

A trading platform blocks users who appear on global sanctions lists during onboarding.

Scenario

Any individual or entity on OFAC SDN, EU Consolidated, UN Security Council, or HM Treasury lists must be prevented from accessing trading functionality.

Expected Outcome

Matched entities receive an automated block notification. Compliance officers receive an alert with match details. A SAR draft is initiated automatically for confirmed matches above the confidence threshold.

Every new customer is assigned a dynamic risk score before gaining access to services.

Scenario

A neobank wants to instantly tier new customers (low/medium/high risk) at signup to determine their initial credit limit and transaction monitoring intensity.

Expected Outcome

Score returned within 3 seconds. Low (0–30): instant account activation. Medium (31–69): limited account pending review. High (70+): account held pending EDD.

A company continuously monitors customers for changes in sanctions or risk status.

Scenario

A payments processor must re-screen all active customers every time a major sanctions list is updated (typically several times per week). Manual batch uploads are operationally unsustainable at scale.

Expected Outcome

KYC-Agent's perpetual monitoring daemon re-screens the portfolio automatically on list update. New hits trigger case creation and compliance officer notification within 60 seconds of list publication.

AI detects fake or altered identity documents during onboarding.

Expected Outcome

Documents flagged as suspected forgeries are quarantined for human review. The forged document image, detected anomalies, and confidence score are presented to the compliance officer in a structured evidence panel.

The following use cases follow the same structured format (Scenario → Walkthrough → Expected Outcome) and will be expanded in the full guide release:

• 07 — Adverse Media Alerts: Flag customers mentioned in negative news during and after onboarding.
• 08 — Simplified Regulatory Compliance: Ensure all users meet AML/KYC requirements automatically.
• 09 — Faster Customer Onboarding: Reduce onboarding time from days to minutes.
• 10 — Centralised Risk Dashboard: View all customer risk profiles in one place.
• 11 — Automated Re-Verification: Trigger re-checks when regulations or risk factors change.
• 12 — Secure Audit Trail Generation: Log every KYC decision for regulators.
• 13 — PEP Screening at Onboarding: Flag politically exposed persons automatically.
• 14 — Age Verification: Verify customer age against official records.
• 15 — Address Verification: Validate physical addresses against government databases.
• 16 — Global Watchlist Cross-Reference: Screen against hundreds of watchlists simultaneously.
• 17 — Liveness Detection: Confirm a live person is presenting documents.
• 18 — Batch Portfolio Screening: Screen entire existing portfolios overnight.
• 19 — Third-Party Due Diligence: Verify subcontractors and suppliers before contract execution.
• 20 — Risk-Based Onboarding Routing: Route customers to simplified or enhanced flows.
• 21 — Digital ID Wallet Acceptance: Accept government-issued digital credentials.
• 22 — Multi-Language Document Processing: Process documents across multiple languages.
• 23 — Email & Phone Verification: Confirm contact details as part of onboarding.
• 24 — Data Privacy Compliance Assurance: Ensure GDPR/CCPA-compliant KYC data handling.

The KYB agent maps complex corporate ownership structures across jurisdictions to identify hidden ultimate beneficial owners (UBOs), even through shell companies.

Scenario

A private equity fund is onboarding a target company registered in Luxembourg with subsidiaries in Cayman Islands, Delaware, and Singapore. The compliance team needs to identify all natural persons who ultimately own or control more than 25% of the structure.

Architecture

KYC-Agent's graph engine uses a breadth-first traversal algorithm across corporate registry data, filing databases, and beneficial ownership registers. Ownership percentages are calculated transitively through each layer.

Expected Outcome

A visual ownership graph is generated with all entities and ownership percentages. UBOs above the 25% threshold are flagged, their identity verification status is shown, and the evidence chain is available for download.

AI agents correlate shipment data, invoices, and counterparties to detect suspicious trade patterns such as over/under-invoicing.

Scenario

A trade finance bank needs to detect whether a customer's export invoices are priced anomalously compared to market benchmarks — a classic TBML indicator.

Configuration

Configure the TBML detection module with the relevant commodity codes, benchmark data sources (World Customs Organization, UN Comtrade), and deviation thresholds. Typical alert threshold: >30% deviation from median commodity price.

If a director or entity becomes sanctioned, the system automatically flags, suspends, and alerts compliance teams in real time.

Scenario

A compliance team manages 50,000 active corporate clients. On a Tuesday morning, OFAC adds a major financial institution to the SDN list. The team needs every affected client relationship to be surfaced and suspended within minutes.

Walkthrough

1. Sanctions list update received

   KYC-Agent's monitoring daemon detects the OFAC update within 90 seconds of publication.

2. Portfolio re-screened

   All 50,000 entities are re-screened against the updated list using parallel processing. Screening completes in under 4 minutes.

3. Matches suspended

   Accounts with confirmed matches above the confidence threshold have their service access automatically suspended pending review.

4. Compliance team alerted

   Email, in-app, and webhook notifications dispatched with match details and next-action guidance.

High-risk cases are escalated with AI-generated summaries for rapid human decision-making with full audit capture.

Scenario

A complex corporate onboarding case has a risk score of 78, flagged due to an adverse media hit referencing a subsidiary name. The compliance officer needs a concise briefing, not 40 pages of raw data.

Expected Outcome

The AI-generated case summary presents: entity overview, risk score breakdown, evidence snippets with relevance scores, and a recommended decision with reasoning. The officer approves or rejects in one click, with all reasoning captured in the immutable audit log.

Agents re-evaluate entities automatically when ownership changes, sanctions lists update, or new adverse media appears.

Scenario

A law firm managing client retainers needs to ensure that clients who were clean at onboarding remain clean throughout the relationship without manual annual reviews.

Configuration

Enable perpetual KYC under Settings → Monitoring → Perpetual KYC. Set re-trigger conditions: ownership change ≥5%, new sanctions list publication, adverse media relevance score ≥0.7, or annual anniversary trigger.

The following advanced use cases will be expanded in the full guide release with complete architecture notes, configuration snippets, and outcome criteria:

• 04 — Cross-Border Entity Resolution: Resolve identity ambiguity across countries, languages, and data sources.
• 05 — Adverse Media Intelligence with Contextual Scoring: NLP-driven relevance scoring to reduce false positives.
• 06 — Dynamic Risk Scoring Based on Trading Behaviour: Adaptive risk scores from transaction patterns.
• 09 — Graph-Based Detection of Hidden Relationships: Surface fraud rings via shared directors, addresses, and phones.
• 10 — Jurisdictional Regulatory Mapping: Automatically apply country-specific KYC/AML requirements.
• 11 — AI-Powered Document Forgery Detection: Deep learning detection of micro-level document alterations.
• 12 — Automated SAR Drafting: AI-assembled Suspicious Activity Reports with structured evidence.
• 13 — Entity Deduplication Across Data Providers: ML-driven golden record reconciliation.
• 14 — Behavioural Anomaly Detection: Flag unusual activity deviating from baseline profiles.
• 15 — KYC Orchestration Across Multiple Data Providers: Intelligent provider routing by jurisdiction and cost.
• 16 — Corporate Registry Graph Integration: Real-time connection to official registries across jurisdictions.
• 17 — Automated Enhanced Due Diligence (EDD) Packaging: AI-curated evidence packages for compliance review.
• 18 — Predictive Risk Trajectory Modelling: ML prediction of future risk before verification completes.
• 19 — Sanctions Evasion Pattern Recognition: Detect structuring and geographic obfuscation tactics.
• 20 — Multi-Tenant Compliance Isolation: Strict data segregation in multi-tenant SaaS deployments.
• 21 — API-First KYC Orchestration for Embedded Finance: Composable compliance APIs for fintech partners.
• 22 — Commodity-Specific Risk Rule Engines: Bespoke logic for high-risk commodity categories.
• 23 — Automated Periodic Review Scheduling: Risk-tiered review scheduling with AI pre-population.
• 24 — Real-Time FATF Travel Rule Compliance: Originator/beneficiary information validation at threshold.