Use case · KYC & customer onboarding
KYC and customer onboarding in one auditable entity lifecycle
Modern onboarding is not a one-time pass/fail check. Low-risk customers should pass quickly through automated screening. Higher-risk cases branch into enhanced due diligence. Legal entities require beneficial ownership discovery. Approved customers enter ongoing monitoring that can trigger reassessment. Cyoda models all of it as a single CustomerOnboardingCase entity with an explicit entity workflow — named states, criteria-driven transitions, attached processors, and an immutable history of every decision on that entity.
The problem
Onboarding doesn't fit one system
Document and data checks, external screening, casework, and audit are typically split across multiple systems with separate consistency models. A sanctions match in one system has to propagate to the onboarding record in another before a decision can be made — and the evidence of that propagation is rarely stored.
Asynchronous external checks — ID&V, sanctions, PEP, adverse media — fail intermittently and must be retried safely without duplicate side effects. Without a durable state model, retries are either unsafe or require custom idempotency logic to manage.
Low-risk cases should complete in seconds via straight-through processing. But the same path must branch into enhanced due diligence for higher-risk cases without losing the STP evidence. Legal entities add a second dimension: beneficial ownership discovery is a conditional lifecycle branch, not a checkbox.
Onboarding does not end at approval. Ongoing monitoring and trigger-based reassessment are operational requirements — not optional add-ons. In conventional stacks they are background jobs, disconnected from the onboarding record, with no shared history.
The conventional assembly
Onboarding application / CRM
Holds the record but cannot model complex branching, loop-back, or conditional lifecycle branches.
Screening API (sanctions, PEP, adverse media)
Asynchronous results with retry logic written in application code; evidence not stored durably.
Case management system for EDD
Separate data model and consistency boundary; casework outcome must be reconciled back to the onboarding record.
Audit log or compliance database
Assembled separately — does not capture the data available at the exact moment of each decision.
Monitoring jobs / cron tasks
Disconnected from the onboarding lifecycle; trigger-based reassessment is custom code with no shared history.
How you can model it with Cyoda
CustomerOnboardingCase entity workflow in a KYC system
The CustomerOnboardingCase is a Cyoda entity. Its lifecycle can be modelled as an entity workflow graph with named states, criteria-driven transitions, attached processors, and immutable history on the entity, all in one consistency model. The straight-through path stays fast, exceptions route into controlled case handling, and approval transitions into ongoing monitoring rather than a dead end.
ENTITY WORKFLOW
CustomerOnboardingCase
Lifecycle in a KYC system
Pan to explore the entity lifecycle and select a state or transition for details.
Entity lifecycle detail
Select a state or transition to inspect the entity lifecycle semantics.
CustomerOnboardingCase entity workflow JSON
This viewer is driven directly from the CustomerOnboardingCase entity workflow file, including automated ID&V, legal-entity UBO discovery, EDD, approval, rejection, and monitoring.
What the entity contains
This illustrative CustomerOnboardingCase example uses a more realistic KYC model: legal-entity profile, beneficial ownership layers, connected parties, expected activity, requested products, verification outcomes, screening matches, and documentary evidence all sit on the same governed entity record.
CustomerOnboardingCase.json
{
"caseId": "KYC-CASE-2026-004218",
"caseType": "LEGAL_ENTITY_ONBOARDING",
"status": "ENHANCED_DUE_DILIGENCE_REQUIRED",
"clientSegment": "CORPORATE_BANKING",
"bookingLocation": "GB",
"lineOfBusiness": "Treasury Services",
"requestedProducts": [
"OperatingAccount",
"LiquidityManagement",
"InterestRateHedging"
],
"applicant": {
"legalName": "Northstar Manufacturing Holdings Limited",
"tradingName": "Northstar Manufacturing",
"entityType": "PRIVATE_LIMITED_COMPANY",
"registrationNumber": "09876543",
"countryOfIncorporation": "GB",
"incorporationDate": "2012-06-18",
"registeredAddress": {
"line1": "18 Charterhouse Square",
"city": "London",
"postalCode": "EC1M 6AX",
"country": "GB"
},
"operatingAddress": {
"line1": "Unit 4 Riverside Industrial Estate",
"city": "Birmingham",
"postalCode": "B24 9QR",
"country": "GB"
},
"industry": {
"sicCode": "25990",
"description": "Manufacture of fabricated metal products",
"highRiskIndustry": false
},
"expectedActivity": {
"expectedMonthlyTurnover": {
"amount": 4250000,
"currency": "GBP"
},
"expectedMonthlyTransactionCount": 340,
"expectedCountries": ["GB", "DE", "NL", "US"],
"cashIntensiveBusiness": false,
"crossBorderPaymentsExpected": true
}
},
"connectedParties": [
{
"partyId": "CP-001",
"role": "DIRECTOR",
"fullName": "Amelia Rachel Turner",
"dateOfBirth": "1978-03-11",
"nationality": "GB",
"residentialCountry": "GB",
"ownershipPercentage": 0,
"controlType": "BOARD_CONTROL",
"identityVerificationStatus": "VERIFIED",
"screeningStatus": "CLEAR"
},
{
"partyId": "CP-002",
"role": "ULTIMATE_BENEFICIAL_OWNER",
"fullName": "Daniel James Whitmore",
"dateOfBirth": "1969-10-04",
"nationality": "GB",
"residentialCountry": "GB",
"ownershipPercentage": 38.4,
"controlType": "SHARE_OWNERSHIP",
"identityVerificationStatus": "VERIFIED",
"screeningStatus": "POTENTIAL_PEP_MATCH"
},
{
"partyId": "CP-003",
"role": "ULTIMATE_BENEFICIAL_OWNER",
"fullName": "Harbour Peak Investments BV",
"entityType": "PRIVATE_COMPANY",
"countryOfIncorporation": "NL",
"ownershipPercentage": 31.2,
"controlType": "INDIRECT_SHARE_OWNERSHIP",
"beneficialOwnershipResolved": true,
"screeningStatus": "CLEAR"
}
],
"ownershipAndControl": {
"uboDiscoveryRequired": true,
"uboDiscoveryStatus": "COMPLETED",
"ownershipThresholdPercent": 25,
"controlStructureVerified": true,
"layers": [
{
"level": 1,
"entityName": "Northstar Manufacturing Holdings Limited",
"owners": [
{
"ownerName": "Daniel James Whitmore",
"ownerType": "NATURAL_PERSON",
"ownershipPercentage": 38.4,
"ubo": true
},
{
"ownerName": "Harbour Peak Investments BV",
"ownerType": "LEGAL_ENTITY",
"ownershipPercentage": 31.2,
"ubo": false
},
{
"ownerName": "Employee Share Trust",
"ownerType": "TRUST",
"ownershipPercentage": 12.8,
"ubo": false
},
{
"ownerName": "Minority Shareholders",
"ownerType": "AGGREGATED_HOLDERS",
"ownershipPercentage": 17.6,
"ubo": false
}
]
},
{
"level": 2,
"entityName": "Harbour Peak Investments BV",
"owners": [
{
"ownerName": "Sophie Van Dijk",
"ownerType": "NATURAL_PERSON",
"ownershipPercentage": 62.5,
"effectiveOwnershipPercentage": 19.5,
"ubo": false,
"reason": "Below configured 25 percent effective ownership threshold"
}
]
}
]
},
"documents": [
{
"documentId": "DOC-CERT-INC-001",
"type": "CertificateOfIncorporation",
"status": "VERIFIED",
"source": "CompanyRegistry"
},
{
"documentId": "DOC-OWNERSHIP-CHART-002",
"type": "OwnershipChart",
"status": "VERIFIED",
"source": "ClientUpload"
},
{
"documentId": "DOC-ARTICLES-003",
"type": "ArticlesOfAssociation",
"status": "VERIFIED",
"source": "CompanyRegistry"
},
{
"documentId": "DOC-SOURCE-FUNDS-004",
"type": "SourceOfFundsStatement",
"status": "REQUESTED",
"source": "Client"
},
{
"documentId": "DOC-AUDITED-ACCOUNTS-005",
"type": "LatestAuditedAccounts",
"status": "REQUESTED",
"source": "Client"
}
],
"verificationResults": {
"companyRegistryCheck": {
"status": "PASS",
"companyStatus": "ACTIVE",
"registeredAddressMatched": true,
"officersMatched": true
},
"identityVerification": {
"status": "PASS",
"checkedParties": ["CP-001", "CP-002"]
},
"sanctionsScreening": {
"status": "CLEAR",
"screenedSubjects": [
"Northstar Manufacturing Holdings Limited",
"Amelia Rachel Turner",
"Daniel James Whitmore",
"Harbour Peak Investments BV",
"Sophie Van Dijk"
]
},
"pepScreening": {
"status": "POTENTIAL_MATCH",
"matches": [
{
"matchId": "PEP-MATCH-77291",
"subjectPartyId": "CP-002",
"matchedName": "Daniel J Whitmore",
"matchStrength": 0.82,
"category": "FORMER_LOCAL_GOVERNMENT_OFFICIAL",
"requiresReview": true
}
]
},
"adverseMediaScreening": {
"status": "REVIEW_REQUIRED",
"matches": [
{
"matchId": "MEDIA-448120",
"subject": "Northstar Manufacturing",
"category": "REGULATORY_FINE",
"summary": "Historical health and safety fine from 2021",
"materiality": "LOW",
"requiresReview": true
}
]
},
"fraudAndDeviceChecks": {
"status": "PASS",
"applicationIpCountry": "GB",
"emailDomainAgeDays": 3912,
"suspiciousDeviceSignals": false
}
}
}
Criteria on every transition
Each transition — ID&V pass, sanctions clear, risk threshold met — fires only when its criteria evaluate to true. The criteria are part of the entity workflow definition, not scattered across service code.
Processors attach to lifecycle states
The screening processor runs on entry to Automated ID&V. The risk-scoring processor runs on entry to Dynamic Risk Assessment. Both run inside the entity's transactional boundary — not as fire-and-forget calls.
Ongoing monitoring is a state
Approval does not close the entity. It transitions into Active / Ongoing Monitoring. A monitoring alert re-enters the entity lifecycle as a named transition — not a background job reading a separate table.
Illustrative example only. These examples show how a system could be modelled with Cyoda. They are not detailed business requirements or prebuilt Cyoda application templates.
The outcome
What changes when onboarding is native
STP without sacrificing auditability
Low-risk cases complete automated ID&V, sanctions, and PEP checks without human intervention. The immutable event history captures every check result regardless — not only when something goes wrong.
Exception handling inside the same lifecycle
EDD and manual casework are not a separate system. They are named states with their own criteria and attached processors — branching off the same entity, feeding back into the same entity lifecycle.
Decision-time evidence captured by default
The data available at each transition is recorded as part of the entity history. Point-in-time reconstruction for a regulatory exam or internal review is a query, not a rebuild.
UBO and legal-entity complexity in the entity lifecycle
Beneficial ownership discovery and control-structure verification are modelled as conditional states with their own criteria. The path is explicit, not hidden in application code.
Post-approval monitoring, not a dead end
Approval transitions into ongoing monitoring. Trigger-based reassessment and periodic review re-enter the entity lifecycle as first-class transitions — not polling jobs or background cron tasks.
No separate audit layer
Immutable history is how Cyoda stores state. There is no warehouse to load, no audit table to keep in sync, and no reconstruction needed to answer "what did we know at T?"
Production relevance
Why the model matters for compliance and operations
The architecture differences become concrete when a regulator asks questions, an internal review runs, or an exception case needs to be reconstructed.
Cleaner audit and compliance review
Every decision, check result, and exception is part of the entity record. Audit trails are structural, not reconstructed.
Fewer seams across systems
Onboarding, screening, casework, and evidence live in one consistency model. There is no reconciliation between an onboarding system and a separate audit store.
Explicit decision paths for policy review
Criteria on transitions make every routing decision inspectable. How a case reached EDD, or why it was rejected, is queryable directly from the entity history.
Lower operational burden for exceptions
Casework states, human-in-the-loop branches, and reassessment triggers are part of the entity workflow definition — not custom orchestration code that must be maintained separately.
If you're building or evaluating onboarding infrastructure that has to satisfy compliance, audit, and ongoing monitoring requirements, we'd like to talk.