À propos des statuts de candidat – CheckHub

📌 Note sur la terminologie — La nouvelle interface web de CheckHub (Admin) utilise le terme contact afin d'être plus générique, tandis que l'API utilise encore le terme candidat issu de la version d'origine. Les deux désignent la même entité. Cet article emploie candidat pour rester cohérent avec l'API, où ces codes de statut apparaissent.

Chaque candidat géré par CheckHub passe par un cycle de vie représenté par un statut. Comprendre ces statuts est essentiel pour construire une intégration robuste, car ils déterminent l'état dans lequel se trouve un profil de candidat et les actions qui peuvent ou doivent être entreprises.

Fonctionnement des statuts

Chaque statut de candidat comporte trois composants :

Code — un identifiant numérique (ex. 100, 201, 900) utilisé dans les charges utiles de l'API.

Nom — une constante lisible (ex. NEW_CANDIDATE, VALIDATION_IN_PROGRESS) qui décrit le statut spécifique.

Méta-statut — un regroupement de niveau supérieur (ex. NEW_CANDIDATE, PENDING, VALIDATED, ERROR) qui catégorise les statuts en grandes phases du cycle de vie.

Le méta-statut est utile lorsque vous souhaitez simplifier la logique de votre intégration. Au lieu de gérer chaque code de statut individuellement, vous pouvez vous baser sur le méta-statut pour couvrir les principales phases du flux de travail d'un candidat.

Tableau de référence des statuts

Méta-statut	Code	Nom	Description
`NEW_CANDIDATE`	`100`	`CREATED_BY_ADMIN`	Le profil du candidat a été créé manuellement par un administrateur via l'interface CheckHub.
`NEW_CANDIDATE`	`101`	`CREATED_BY_INTEGRATION`	Le profil du candidat a été créé de manière programmatique via l'API ou une intégration tierce.
`PENDING`	`200`	`DOCUMENT_OR_RESOURCE_NEEDED`	Le profil du candidat est en attente de documents, fichiers ou ressources externes requis avant de pouvoir progresser.
`PENDING`	`201`	`COMPLETE`	Toutes les informations et tous les documents requis ont été fournis ; le profil est prêt à être vérifié.
`PENDING`	`202`	`VALIDATION_IN_PROGRESS`	Les fichiers ou les détails du profil du candidat sont en cours de validation manuelle ou automatique.
`VALIDATED`	`300`	`VALIDATED_BY_ADMIN`	Le profil du candidat et toutes les données associées ont été vérifiés et approuvés avec succès par un administrateur.
`VALIDATED`	`301`	`VALIDATED_BY_AUTO_CHECK`	Le profil du candidat a passé avec succès toutes les vérifications automatiques et est validé.
`ERROR`	`900`	`REJECTED_BY_ADMIN`	Le profil du candidat a été vérifié manuellement et rejeté par un administrateur.
`ERROR`	`901`	`REJECTED_BY_INTEGRATION`	Une intégration externe ou un processus API a signalé un problème et rejeté le profil du candidat.
`ERROR`	`902`	`REJECTED_BY_AUTO_CHECK`	Les règles de vérification automatique du système ont échoué, entraînant un rejet automatique du candidat.

Vue d'ensemble des méta-statuts

NEW_CANDIDATE — La phase initiale du cycle de vie du candidat. Le profil a été créé avec succès dans le système, mais aucun travail de vérification n'a encore commencé.

PENDING — La phase opérationnelle active. Le candidat est soit en train de fournir les ressources requises, soit en attente de traitement, soit actuellement dans la file de vérification.

VALIDATED — L'état final réussi. Le candidat a satisfait à tous les critères (via des règles automatiques ou une vérification humaine) et est entièrement approuvé.

ERROR — Quelque chose s'est mal passé. Le profil a été rejeté par un administrateur, une routine d'automatisation ou un système externe. Une intervention active ou une nouvelle soumission est généralement nécessaire pour sortir le candidat de cet état.

Conseils pour les intégrateurs

Lors du polling ou de la réception de webhooks, utilisez le code numérique pour une correspondance précise des statuts et le méta-statut pour une logique de cycle de vie plus large.

N'oubliez pas que le méta-statut PENDING couvre plusieurs sous-états (200, 201, 202) — assurez-vous que votre intégration prenne en compte le fait qu'un candidat traverse la collecte des ressources, la complétion puis la validation tout en restant sous le même méta-statut.

Les méta-statuts NEW_CANDIDATE et ERROR distinguent tous deux, via leurs codes, les actions déclenchées par un administrateur de celles déclenchées par une intégration ou une automatisation — basez-vous sur le code spécifique lorsque vous avez besoin de connaître l'origine d'un changement de statut.

Un candidat créé via votre intégration démarrera au code 101 (CREATED_BY_INTEGRATION), un signal utile pour réconcilier les enregistrements de votre côté.