Ce guide vous accompagne dans le processus d'envoi d'un fichier vers CheckHub via l'API. C'est utile lorsque vous possédez déjà un document (ex. un scan de carte d'identité) et que vous souhaitez que CheckHub en extraie les données et exécute les validations — le tout dans le contexte d'un candidat.
Prérequis :
- Un API token valide (header Authorization). Voir How to Create Your First API Token.
- Le document type ID correspondant au type de document que vous souhaitez envoyer (ex. carte d'identité, permis de conduire).
Processus
1. Récupérer ou créer le candidat
Vous avez besoin de l'ID et du token du candidat avant de pouvoir uploader quoi que ce soit. Un token candidat ressemble à ceci : 02yEXtzgnTPpuabAC
Si le candidat existe déjà, récupérez son token en effectuant une recherche via son ID ou son lien privé.
Si vous devez créer un nouveau candidat, utilisez l'endpoint Create a new candidate :
- Lien vers la documentation API : Create a new candidate
La réponse retournera à la fois l'ID et le token du candidat dans le payload de confirmation.
2. Demander un document
Avant d'uploader un fichier, vous devez créer un conteneur de document qui le recevra. Cela se fait via l'endpoint Candidate Document Type.
- Lien vers la documentation API : Candidate Document Type
Vous devez fournir :
- Le candidate ID (de l'étape 1)
- Le document type ID (ex. l'ID correspondant à « carte d'identité »)
Cette étape indique à CheckHub quel type de document attendre et prépare le pipeline d'extraction et de validation.
3. Passer à l'authentification par token candidat
Important : À partir de cette étape, vous devez vous authentifier en utilisant le candidate token au lieu de votre API token habituel. Définissez le header X-CSRF-TOKEN avec la valeur du token candidat.
- Lien vers la documentation API : Authentication
Exemple de header :
X-CSRF-TOKEN: 02yEXtzgnTPpuabAC4. Uploader le fichier
Uploadez votre fichier via l'endpoint Upload file for the candidate document, en vous authentifiant avec le X-CSRF-TOKEN.
- Lien vers la documentation API : Upload file for the candidate document
- Collection Postman : Upload file for the candidate document
Attention : Avant d'uploader, définissez correctement le paramètre isMultiple :
- Document simple (un seul fichier) : définir
isMultiple=false
- Document recto-verso (recto + verso, ex. carte d'identité) : définir
isMultiple=true
Règles de positionnement
Lors de l'upload de fichiers, le paramètre position détermine l'ordre des pages dans le PDF généré :
- Documents recto-verso : les positions doivent être strictement
0(recto) et1(verso).
- Documents multi-parties : utilisez des positions séquentielles
0, 1, 2, ...— l'ordre détermine les pages dans le PDF généré.
5. Finaliser l'upload (uniquement si isMultiple=true)
Bon à savoir : Cette étape n'est nécessaire que lorsque isMultiple=true. Si isMultiple=false, la confirmation est automatique une fois l'upload terminé — vous pouvez ignorer cette étape.
Si vous avez défini isMultiple=true, vous devez finaliser le processus en appelant l'endpoint Complete upload.
- Lien vers la documentation API : Complete single or multiple document upload
- Collection Postman : Complete single or multiple document upload
Après cette étape, CheckHub traitera le document via le pipeline d'extraction et de validation configuré.
Référence rapide
Étape | Action | Méthode d'authentification |
1 | Récupérer ou créer le candidat | Authorization (API token) |
2 | Demander un document | Authorization (API token) |
3 | Changer d'authentification | X-CSRF-TOKEN (candidate token) |
4 | Uploader le fichier | X-CSRF-TOKEN (candidate token) |
5 | Finaliser l'upload | X-CSRF-TOKEN (candidate token) |
Besoin d'aide ?
Accédez à la documentation API complète ici ou explorez la collection Postman pour des exemples de requêtes prêts à l'emploi.