Compliance Check ( compliance_check )

Role

The check is the atomic traceability unit for KYC/KYB and compliance. It may be produced during onboarding, checkout, ongoing monitoring, manual action, or imported from an external system. When attached to an onboarding case, it also appears in the checks de GET /v1/onboarding-cases/:id.

check_type and scope are free-form strings. The field provider is also free-form when an external provider produced the check, but remains null for a manual check without an identified provider.

Identifier and structure

Each check has a stable identifier prefixed with cpc_.

{
"object": "compliance_check",
"id": "cpc_9a8b7c6d5e4f3a2b",
"onboarding_case_id": "obc_3f8a1d9c2b4e7f6a",
"process_instance_id": "pci_1b2c3d4e5f6a7b8c",
"node_id": "kyc_identity_check",
"subject_type": "contact",
"subject_id": "ctc_d12e3f4a5b6c7d8e",
"scope": "director",
"check_type": "kyc",
"provider": "stripe_identity",
"result": "passed",
"raw_response": {
  "verification_session": "vs_1Abc2Def",
  "status": "verified"
},
"valid_until": "2028-06-17T00:00:00.000Z",
"source_reference": null,
"metadata": {},
"checked_at": "2026-06-17T10:15:00.000Z",
"created_at": "2026-06-17T10:00:00.000Z"
}

Check subject

Each check targets exactly one subject, identified by the combination subject_type + subject_id.

The subject determines the merchant owning the check. When an onboarding_case_id or a process_instance_id is supplied, this context must belong to the same merchant. A check of type contact_role (contact_role) is useful when verification concerns the function exercised by a person rather than the person alone.

Dimensions libres

check_type and scope are free-form business dimensions. provider is an optional external-provenance dimension:

These dimensions allow precise check queries through GET /v1/compliance-checks by combining filters:

GET /v1/compliance-checks
?onboarding_case_id=obc_3f8a
&subject_type=contact
&check_type=kyc
&result=passed

Result and immutability

The field result represents the verification outcome. A check created with result: "pending" can be updated through POST /v1/compliance-checks/:id. Once the result is non-pending, the check becomes immutable — any update attempt returns an error 400.

A check may be created directly with a non-pending result when the provider responds synchronously. In that case, the corresponding event is emitted immediately at creation.

Validity

The field valid_until lets you express a validity period for the check result. Once this date passes, the result is considered stale — a new check of the same type should be performed before entering or renewing a relationship with the subject.

When valid_until is exceeded for a business result (passed, failed or manual_review), Ormuz emits compliance_check.expired. The field result is not modified: the check keeps its historical result, but its time validity has expired.

Typical durations:

• Individual KYC: 1 to 2 years depending on applicable regulation
• Sanctions screening: a few months because lists change frequently
• SIRENE data: 6 months to 1 year for company information

Flux asynchrone

Most verification providers are asynchronous: they accept the request immediately and return the result through a webhook. The recommended pattern is to create the check with result: "pending", then update it when the result becomes available.

1. Create the check immediately with a pending result

POST /v1/compliance-checks

{
"onboarding_case_id": "obc_3f8a",
"subject_type": "contact",
"subject_id": "ctc_d12e",
"scope": "director",
"check_type": "kyc",
"provider": "stripe_identity",
"result": "pending"
}

Creation returns the check identifier and initial result, among other fields:

{
"id": "cpc_9a8b",
"result": "pending"
}

2. Update after the provider callback

POST /v1/compliance-checks/cpc_9a8b

{
"result": "passed",
"raw_response": {
  "verification_session": "vs_1Abc2Def",
  "status": "verified"
}
}

The response confirms the result and causes compliance_check.passed.

{
"result": "passed"
}

In processes

The node has_valid_compliance_check lets you reuse an existing check when its nature, freshness, and validity period satisfy the process need. The subject may be a platform.company or a platform.contact.

The selection strategy is explicit: most_favorable retains the latest passed eligible check when one exists, latest uses the latest eligible check as authoritative, and most_conservative retains the latest non-passed check when one exists. Ormuz therefore applies no universal supersession rule between producers.

The routes are valid and not_valid. The output compliance_check exposes the check actually selected by the strategy to justify the decision; it is absent only when no eligible check exists. The freshness max_age requested by the process and the valid_until defined by the producer remain two separate constraints.

Events

A creation directly in passed, failed, manual_review or error first emits compliance_check.created, then the event corresponding to the result. A check created in pending emits only created until resolution.

When a check in manual_review is attached to onboarding, Ormuz then emits onboarding_case.review_required as a consequence on the case. Its triggering_check_id identifies the check that caused this review; this field remains optional because onboarding may require review for other reasons.