B2B customer onboarding

Open a case for a company or person, collect missing information, run required business, KYC, KYB, compliance, or fraud checks, then attach verified objects before approving or rejecting onboarding.

Business objective

An onboarding_case carries one end-to-end onboarding attempt. It retains subject type, initial data, completed checks, associated process, and final decision. It can start before the company or contact exists in Ormuz.

The process progressively turns declarative information into usable business objects. It may search for an existing company, create or enrich a company, identify its contacts, collect supporting documents, call partners, and request human review.

Decision responsibility

The case centralizes evidence and outcome. Merchant process policy determines required checks, their order, manual-review cases, and approval conditions.

Company or individual onboarding

`subject_type`	Usage	Condition before approval
`company`	Onboard a customer company, buyer, supplier, or other B2B business.	A `company` must be attached to the case.
`individual`	Onboard a person in the context of a company, for example a representative or signatory.	A `company` and a `contact` must be attached.

If the company or contact already exists, supply its ID at creation. Otherwise use initial_data to prefill the journey; the process decides when to search, create, and attach persisted objects.

Prerequisites

Element	Role
Merchant	Defines the scope of data, process, and extension configurations.
Process launcher onboarding	Associates new cases with an onboarding process definition. Several launchers may coexist for the merchant.
Return URLs	Return the user to your application after a hosted user action.
Decision policy	Defines blocking checks, expected evidence, and review cases.

A User Journey is required only when the process waits for a user action. Onboarding fed by API, synchronization, or external services can run without a redirect; your system then waits for the final decision event.

Target journey

Open the case

Resolve the subjects

Collect if needed

Run the checks

Decide / review

Finalize the case

User collection and automated checks may run in parallel or conditionally according to the process.

Open and deduplicate the case

Ormuz rejects a second active case carrying the same company, contact, or business key.

Resolve the subjects

The process searches for existing objects or builds the company and contact from initial data.

Collect and verify

Forms, internal checks, and configured extensions produce the required information and evidence.

Decide and finalize

The process attaches persisted objects to the case, then closes it with an approved or rejected.

Open the case

Appelez POST /v1/onboarding-cases decision from your backend. The initial_data.company et initial_data.contact data follows the corresponding public create fields, but does not immediately create those objects.

POST /v1/onboarding-cases
Content-Type: application/json

{
  "merchant_id": "mer_abc123",
  "subject_type": "company",
  "return_url": "https://app.example/onboarding/complete",
  "source_reference": "CRM-ACCOUNT-1042",
  "initial_data": {
    "company": {
      "legal_name": "ACME France SAS",
      "registration_number": "123456789",
      "registration_country": "FR",
      "is_buyer": true
    },
    "contact": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com"
    }
  }
}

"onboarding_case":{12 items"id":"obc_abc123"
"object":"onboarding_case"
"subject_type":"company"
"status":"open"
"decision_status":"pending"
"merchant_id":"mer_abc123"
"company_id":null
"contact_id":null
"source_reference":"CRM-ACCOUNT-1042"
"process_instance_id":"pci_abc123"
"url":"https://hosted.example/access/..."
"checks":[]0 items
}

{
  "id": "obc_abc123",
  "object": "onboarding_case",
  "subject_type": "company",
  "status": "open",
  "decision_status": "pending",
  "merchant_id": "mer_abc123",
  "company_id": null,
  "contact_id": null,
  "source_reference": "CRM-ACCOUNT-1042",
  "process_instance_id": "pci_abc123",
  "url": "https://hosted.example/access/...",
  "checks": []
}

The response contains the obc_*ID, process instance, and a contextualized User Journey URL. Use this URL only when the process contains a user action; otherwise let the journey run server-side. Store the case ID with your CRM, ERP, or e-commerce reference.

Prevent duplicates

Provide a stable source_reference or explicit dedupe_key. Without a supplied key, Ormuz attempts to derive one from source reference, email, and registration number.

Collect data and produce checks

Known data prefills process context. Subsequent steps should ask the user only for missing information or information requiring explicit confirmation.

Capability	Usage examples	Expected output
Object resolution	Search for a company by registration, find a contact by email, create missing objects.	`company` et `contact` persisted.
User collection	Contact details, activity, beneficial owners, consents, or supplementary information.	Structured values reusable by subsequent nodes.
Internal checks	Completeness, eligibility rules, consistency, validation of a role or authority.	Traceable decision or evidence.
Partner checks	KYC, KYB, sanctions, PEP, fraud, identity, bank account, or scoring.	Normalized result and recommended action.

A compliance_check primarily concerns its subject. It can additionally be attached to the onboarding case and process that produced it, but these contexts are optional. Its result may be pending, passed, failed, error or manual_review. The case detail exposes checks attached to it. A provider result is not automatically a final onboarding decision: process policy remains responsible for interpreting the check.

Decide, request review, or reject

A check in manual_review first emits compliance_check.review_requiredmay trigger onboarding_case.review_required . If attached to this case, Ormuz then emits

Decision	Condition typique	Effet
Approuver	as a consequence on onboarding. Your process can wait for an operator decision, request additional information, or continue with an enhanced level of control.	`status=completed`, `decision_status=approved`
Revue manuelle	Required objects are attached and every blocking check is favorable.	`status=open`, `decision_status=pending`
Rejeter	Ambiguous result, missing document, or rule requiring human validation.	`status=completed`, `decision_status=rejected`
Annuler	Unfavorable blocking check or unmet eligibility criterion.	`status=cancelled`, `decision_status=pending`

Use finalize_onboarding_case for an explicit final decision; cancellation is reserved for abandonment or a case that is no longer relevant.

Case lifecycle

The case separates two axes. status describes its lifecycle; decision_status separately describes the onboarding decision. Ongoing collection or human review therefore does not create an additional intermediate status: the case remains open until the decision is terminal.

`status`	`decision_status`	Signification
`open`	`pending`	Active case: collection, checks, or review may still be in progress.
`completed`	`approved`	Onboarding closed with a favorable decision.
`completed`	`rejected`	Onboarding closed with an unfavorable decision.
`cancelled`	`pending`	Case canceled without an approval or rejection decision.

completed et cancelled are terminal for this case. A new onboarding need opens a new case rather than rewriting the decision of a closed case.

Events and tracking

Event	Utilisation
`onboarding_case.company.created`	Track the opening of a company onboarding.
`onboarding_case.individual.created`	Track the opening of an individual onboarding.
`onboarding_case.review_required`	Create an operator task or notify a compliance team.
`onboarding_case.approved`	Activate the customer or synchronize approved objects.
`onboarding_case.rejected`	Block activation and apply the handling defined by your policy.
`onboarding_case.completed`	Observe every decided closure, favorable or unfavorable.
`onboarding_case.cancelled`	Handle abandonment of a case without a final decision.

After a redirect from the User Journey, always reread the case server-side. For an automated journey, wait directly for onboarding_case.approved, onboarding_case.rejected, onboarding_case.cancelled or a review event, then retrieve the case and its checks.

Before opening a new case for a known company, searching approved onboardings lets you reuse a prior decision according to your validity policy.

Integration checklist

Choose company or individual according to the subject actually being onboarded.
Configure at least one active onboarding launcher and explicitly select the process_definition_id when several exist.
Pass existing objects or prefill only data already known.
Use a stable source reference or deduplication key.
Request a User Journey only when the process is waiting for a user action.
Trace every important check with its subject, optional provider, and result.
Explicitly define which outcomes require review or block approval.
Attach a company, and a contact for individual onboarding, before approval.
Handle decision events idempotently and reread the case before activation.

← PreviousCommercial dispute Next →Buyer credit management