Dossier d’onboarding ( onboarding_case )

Un onboarding_case représente le dossier d'entrée en relation avec une entreprise. Il pilote un processus d'orchestration qui collecte les données, exécute les vérifications de conformité, et rend une décision d'approbation ou de rejet. Il fournit également une URL vers un parcours utilisateur que le sujet complète lui-même.

Rôle

Le dossier d'onboarding est l'objet central des flux KYC et KYB. Il porte deux dimensions distinctes : le cycle de vie du dossier (est-il encore actif ?) et la décision finale (le sujet est-il approuvé ?). Cette séparation permet de distinguer un dossier clôturé avec un refus d'un dossier annulé avant toute décision.

À la création, un processus d'orchestration est lancé automatiquement. Ce processus est responsable de collecter les pièces justificatives, d'appeler les providers de vérification d'identité, et de conclure en rattachant le dossier aux objets company et contact créés au fil du processus.

Identifiant et structure

Chaque dossier porte un identifiant stable préfixé par obc_. Le champ url est fourni directement dans la réponse à la création — aucun appel supplémentaire n'est nécessaire pour récupérer le lien à transmettre au sujet.

JSON

"onboarding_case":{22 items"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":{1 item"company":{...}3 items
}
"dedupe_key":"source_reference:crm-prospect-00512"
"locale":"fr"
"return_url":"https://example.com/onboarding/return"
"source_reference":"CRM-PROSPECT-00512"
"metadata":{}0 items
"checks":[]0 items
"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"
}

{
"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"
}

Type de sujet

Le champ subject_type détermine la nature du sujet à onboarder et les contraintes de clôture qui en découlent.

subject_type	Sujet	Requis pour approuver
`company`	Entreprise (personne morale)	`company_id` doit être renseigné
`individual`	Particulier (personne physique)	`company_id` et `contact_id` doivent être renseignés

La décision d'onboarding reste portée par le dossier via decision_status. Elle n'est pas projetée sur la company : plusieurs dossiers peuvent coexister ou être rejoués, et la politique qui autorise ensuite une opération appartient au processus ou au marchand.

Champs

Champ	Type	Description
`id`	`string`	Identifiant du dossier (préfixe obc_).
`object`	`string`	Toujours "onboarding_case".
`merchant_id`	`string`	Marchand propriétaire du dossier.
`subject_type`	`enum`	Type de sujet : "company" ou "individual".
`status`	`enum`	Cycle de vie : open, completed, cancelled.
`decision_status`	`enum`	Décision finale : pending, approved, rejected.
`company_id`	`string`	Entreprise rattaché au dossier (cmp_…). Peut être null jusqu'à la résolution dans le processus.
`contact_id`	`string`	Contact principal rattaché (ctc_…). Requis pour les dossiers "individual" approuvés.
`process_definition_id`	`string`	Définition de processus d'onboarding lancée (prd_…).
`process_instance_id`	`string`	Instance de processus qui pilote actuellement le dossier (pci_…). Peut changer lors d’une reprise corrective.
`process_status`	`enum`	État d’exécution dérivé de l’instance associée : running, waiting, stopping, completed, failed, retry_exhausted, superseded, stopped ou null.
`url`	`string`	URL de l'expérience d'onboarding hébergée. Fournie dans la réponse de création.
`initial_data`	`object`	Données de pré-remplissage injectées dans le processus. Voir section dédiée.
`dedupe_key`	`string`	Clé de déduplication. Auto-générée si absente. Voir section dédiée.
`locale`	`string`	Langue du parcours utilisateur (ex. fr, en).
`return_url`	`string`	URL de redirection après complétion de l'expérience.
`source_reference`	`string`	Référence dans votre système (CRM, dossier interne…).
`metadata`	`object`	Map plate de scalaires `string \| number \| boolean`, selon la convention metadata de l’API.
`checks`	`array`	Contrôles de conformité rattachés au dossier. Inclus uniquement sur GET /:id.
`opened_at`	`datetime`	Date d'ouverture du dossier.
`closed_at`	`datetime`	Date de clôture (statut final). null si encore ouvert.
`created_at`	`datetime`	Date de création.
`updated_at`	`datetime`	Date de dernière mise à jour.

Cycle de vie et décision

Le champ status décrit le cycle de vie du dossier. Le champ decision_status exprime la décision finale. Seules certaines combinaisons sont valides.

État initialopen

completed

cancelled

Combinaisons valides

status	decision_status	Valide	Note
`open`	`pending`	oui	État initial. Aucune décision prise.
`completed`	`approved`	oui	Décision favorable. Company (et contact si individual) obligatoires.
`completed`	`rejected`	oui	Décision défavorable.
`completed`	`pending`	non	Un dossier completed doit porter une décision.
`cancelled`	`pending`	oui	Annulation sans décision. decision_status ne peut pas être non-pending.
`cancelled`	`approved/rejected`	non	Un dossier annulé ne peut pas porter de décision.

Contraintes de clôture

Un dossier en statut final (completed ou cancelled) ne peut plus être modifié. Si vous utilisez le node finalize_onboarding_case, le paramètre status prend directement la valeur de la décision ( "approved" ou "rejected"), pas le statut du dossier — le node applique lui-même status: completed.

Processus associé

Un dossier créé avec un processus d'onboarding expose l'instance qui pilote actuellement son traitement via process_instance_id. Le champ process_status donne l'état de cette instance. Il est dérivé de l'exécution associée et reste distinct de status et decision_status.

Exemple	Lecture
`status: open` + `process_status: running`	Le dossier est ouvert et son traitement est en cours.
`status: open` + `process_status: stopped`	L'exécution a été arrêtée, mais le dossier n'a pas été annulé automatiquement.
`status: completed` + `decision_status: approved` + `process_status: completed`	Le dossier porte une décision favorable et l'exécution est terminée.

La décision reste explicite

Une instance completed n'approuve ni ne rejette automatiquement le dossier. Une instance failed, retry_exhausted ou stopped ne le passe pas automatiquement à cancelled. Le node finalize_onboarding_case et les nodes d'update explicites restent responsables de la décision et du cycle de vie métier.

Lorsqu'un retry manuel, un fork retry_step / skip_step ou la reprise d'une étape utilisateur crée une nouvelle instance pour poursuivre le même onboarding, process_instance_id bascule vers cette nouvelle instance. Elle devient l'exécution canonique du dossier et process_status reflète son état. L'ancienne instance reste consultable pour la traçabilité.

Voir Erreurs et idempotence pour les règles de reprise et de transfert de l'instance associée.

Données initiales

Le champ initial_data permet de pré-remplir les données du sujet avant que le processus démarre. Ces données sont injectées dans le processus sous forme de variables de type draft :

Clé dans initial_data	Variable dans le processus	Champs acceptés
`initial_data.company`	`company_draft`	legal_name, trade_name, legal_form, registration_number, registration_country, tax_identifier, registered_address, incorporation_date, share_capital, currency, is_buyer, is_supplier, source_reference, metadata
`initial_data.contact`	`contact_draft`	full_name, first_name, last_name, email, phone, job_title, preferred_locale, source_reference, metadata

Ces variables draft sont disponibles dès le démarrage du processus et peuvent être passées aux nodes create_company ou create_contact pour créer les objets réels sans redemander les données déjà connues.

Création avec des données initiales préremplies

HTTP

POST /v1/onboarding-cases

{4 items"subject_type":"company"
"locale":"fr"
"source_reference":"CRM-PROSPECT-00512"
"initial_data":{1 item"company":{...}4 items
}
}

{
"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
  }
}
}

Déduplication

La plateforme empêche l'ouverture de plusieurs dossiers actifs pour le même sujet. La détection repose sur une clé de déduplication (dedupe_key).

Si dedupe_key n'est pas fourni, il est généré automatiquement selon la priorité suivante :

source_reference:<valeur normalisée> — si source_reference est présent
person_company:<email>:<pays>:<numéro> — si email et numéro d'entreprise sont dans initial_data
company_registration:<pays>:<numéro> — si seul le numéro d'entreprise est disponible
person_email:<email> — si seul l'email est disponible

Si un dossier actif (status: open) existe déjà avec la même clé, la création retourne une erreur 409 :

HTTP

409 Conflict

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

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

Pour ignorer la déduplication dans des cas spécifiques (ex. re-onboarding volontaire), passez un dedupe_key unique aléatoire à chaque création.

Checks de conformité

Chaque dossier porte un tableau checks de contrôles de conformité réalisés au fil du processus. Ces contrôles sont accessibles sur GET /v1/onboarding-cases/:id (non inclus dans la liste).

Chaque check enregistre un résultat de vérification avec son provider, son scope, le sujet vérifié, et un horodatage. Les résultats possibles sont :

Résultat	Signification
`pending`	Vérification en attente de résultat
`passed`	Vérification réussie
`failed`	Vérification échouée
`manual_review`	Résultat ambigu, nécessite une révision manuelle
`error`	Erreur technique lors de la vérification

Le node create_compliance_check permet d'enregistrer une trace de vérification dans le processus. Il accepte comme sujet (subject) une company, un contact ou un contact_role. Le champ check_type peut prendre des valeurs libres (ex. kyc, kyb, sanctions, pep).

Dans les processus

Le dossier est injecté automatiquement comme entrée du processus d'onboarding sous la variable onboarding_case (type platform.onboarding_case). Cinq nodes permettent de le piloter :

Node	Rôle	Entrées / sorties clés
`finalize_onboarding_case`	Résout les sujets, les rattache et applique la décision finale — pattern recommandé	Accepte : onboarding_case, status (approved \| rejected), company?, contact? · Produit : onboarding_case, company, contact
`update_onboarding_case_status`	Met à jour status et/ou decision_status	Accepte : onboarding_case, status (open \| completed \| cancelled), decision_status? · Produit : onboarding_case
`update_onboarding_case_subject`	Rattache une company et/ou un contact au dossier sans clore	Accepte : onboarding_case, company?, contact?, source_reference, dedupe_key · Produit : onboarding_case
`create_compliance_check`	Enregistre un contrôle de conformité sur un sujet, avec rattachement optionnel au dossier	Accepte : onboarding_case?, scope, subject, check_type, provider?, result, raw_response?, valid_until? · Produit : compliance_check
`has_already_onboarded`	Vérifie si la company a déjà un onboarding approuvé et clôturé	Accepte : company, contact? · Route `yes` (produit onboarding_case, completed_at) / `no`

finalize_onboarding_case vs update_onboarding_case_status

Dans finalize_onboarding_case, le paramètre status prend "approved" ou "rejected" (la décision), pas "completed". Le node applique lui-même status: completed et résout les sujets en une seule opération. Utilisez update_onboarding_case_status seulement si la logique de rattachement a déjà été gérée séparément.

Événements

Événement	Déclencheur
`onboarding_case.company.created`	Dossier créé avec subject_type "company".
`onboarding_case.individual.created`	Dossier créé avec subject_type "individual".
`onboarding_case.completed`	Dossier clôturé avec decision_status "approved".
`onboarding_case.rejected`	Dossier clôturé avec decision_status "rejected".

L'événement de création est différencié par subject_type, ce qui permet de déclencher des processus d'onboarding distincts selon la nature du sujet sans filtrage supplémentaire dans le déclencheur. Le passage à cancelled ne déclenche pas d'événement dédié.

L'endpoint GET /v1/onboarding-cases/search permet de retrouver le dernier dossier complété et approuvé pour une company (et optionnellement un contact) donnée, sans parcourir la liste paginée :

HTTP

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

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

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

← PrécédentCheckout session Suivant →Contrôle de conformité