Onboarding case ( onboarding_case )

Role

The onboarding case is the central object of KYC and KYB flows. It carries two distinct dimensions: the case lifecycle of the case — is it still active? — and the final decision . This separation distinguishes a case closed with rejection from a case canceled before any decision.

At creation, an orchestration process starts automatically. This process is responsible for collecting supporting documents, calling identity-verification providers, and concluding by attaching company and contact objects created during the process.

Identifier and structure

Every case has a stable identifier prefixed with obc_. The The url field contains the User Journey URL returned directly in the creation response — no additional call is required to retrieve the link to send to the subject.

{
"object": "onboarding_case",
"id": "obc_3f8a1d9c2b4e7f6a",
"subject_type": "company",
"status": "open",
"decision_status": "pending",
"company_id": null,
"contact_id": null,
"process_definition_id": "prd_8a2b3c4d5e6f7a8b",
"process_instance_id": "pci_1b2c3d4e5f6a7b8c",
"process_status": "running",
"url": "https://onboarding.example.com/o/obc_3f8a…",
"initial_data": {
  "company": {
    "legal_name": "Dupont & Fils SARL",
    "registration_number": "841234567",
    "registration_country": "FR"
  }
},
"dedupe_key": "source_reference:crm-prospect-00512",
"locale": "fr",
"return_url": "https://example.com/onboarding/return",
"source_reference": "CRM-PROSPECT-00512",
"metadata": {},
"checks": [],
"opened_at": "2026-06-17T09:00:00.000Z",
"closed_at": null,
"created_at": "2026-06-17T09:00:00.000Z",
"updated_at": "2026-06-17T09:00:00.000Z"
}

Subject type

The field subject_type determines the nature of the subject being onboarded and resulting closure constraints.

The onboarding decision remains carried by the case through decision_status. It is not projected onto the company: multiple cases may coexist or be replayed, and policy authorizing a later operation belongs to the process or merchant.

Fields

Lifecycle and decision

The field status describes the case lifecycle. The decision_status field expresses the final decision. Only certain combinations are valid.

Combinaisons valides

Associated process

A case created with an onboarding process exposes the instance currently driving it through process_instance_id. The process_status gives the state of this instance. It is derived from the associated execution and remains distinct from status and decision_status.

When a manual retry, a fork retry_step / skip_step or resumption of a user step creates a new instance to continue the same onboarding, process_instance_id switches to this new instance. It becomes the canonical execution of the case and process_status reflects its state. The old instance remains available for traceability.

See Errors and idempotency for resume and associated-instance transfer rules.

Initial data

The field initial_data allows pre-filling subject data before the process starts. This data is injected into the process as variables of type draft :

These draft variables are available as soon as the process starts and may be passed to nodes create_company or create_contact to create the actual objects without asking again for already-known data.

Creation with prefilled initial data

POST /v1/onboarding-cases

{
"subject_type": "company",
"locale": "fr",
"source_reference": "CRM-PROSPECT-00512",
"initial_data": {
  "company": {
    "legal_name": "Dupont & Fils SARL",
    "registration_number": "841234567",
    "registration_country": "FR",
    "is_buyer": true
  }
}
}

Deduplication

The platform prevents opening several active cases for the same subject. Detection relies on a deduplication key (dedupe_key).

When dedupe_key is not supplied, it is automatically generated according to this priority:

1. source_reference:<normalized value> — when source_reference is present
2. person_company:<email>:<country>:<number> — when email and company number are present in initial_data
3. company_registration:<country>:<number> — when only company number is available
4. person_email:<email> — when only email is available

If an active case (status: open) already exists with the same key, creation returns an error 409 :

409 Conflict

{
"error": {
  "message": "An active onboarding case already exists for this dedupe key"
}
}

To bypass deduplication in specific cases, for example intentional re-onboarding, pass a dedupe_key random unique value on every creation.

Compliance checks

Each case carries an array checks of compliance checks performed during the process. These checks are available on GET /v1/onboarding-cases/:id (not included in the list).

Every check records a verification result with its provider, scope, verified subject, and timestamp. Possible results are:

The node create_compliance_check lets the process record a verification trace. It accepts as subject (subject) a company, contact, or contact_role. The check_type field may take free-form values (for example kyc, kyb, sanctions, pep).

In processes

The case is automatically injected as input to the onboarding process under the variable onboarding_case (type platform.onboarding_case). Five nodes can operate it:

Events

The creation event is differentiated by subject_type, allowing distinct onboarding processes by subject nature without extra trigger filtering. Transitioning to cancelled does not emit a dedicated event.

L'endpoint GET /v1/onboarding-cases/search lets you retrieve the latest completed and approved case for a given company and optionally contact without traversing the paginated list:

GET /v1/onboarding-cases/search?company_id=cmp_3a8f

{
"object": "onboarding_case_search_result",
"onboarding_case": {
  "id": "obc_3f8a",
  "status": "completed"
},
"completed_at": "2026-01-15T14:30:00.000Z"
}