Dossier d’onboarding (onboarding_case)

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.

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

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

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.

Combinaisons valides

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.

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 :

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

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

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 :

1. source_reference:<valeur normalisée> — si source_reference est présent
2. person_company:<email>:<pays>:<numéro> — si email et numéro d'entreprise sont dans initial_data
3. company_registration:<pays>:<numéro> — si seul le numéro d'entreprise est disponible
4. 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 :

409 Conflict

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

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 :

Événements

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 :

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