Créer une session
POST /v1/sessions · clé secrète sk_…
Crée une vérification pour un usager et réserve son prix sur votre wallet (mode live). La réponse contient le client_secret à transmettre à votre front pour ouvrir le SDK. Il expire au bout de 15 minutes si l'usager ne commence pas, et ne vaut que pour cette session.
Appelez cette route depuis votre serveur uniquement. Votre clé secrète ne doit jamais apparaître dans une application mobile ou un navigateur.
Paramètres du corps
Corps JSON (Content-Type: application/json).
client_reference_id string facultatif
Votre identifiant de l'usager. Renvoyé dans la session et dans chaque webhook ; permet de filtrer la liste des sessions. (255 caractères au plus)
metadata object facultatif
Jusqu'à 20 paires clé/valeur (clés de 1 à 40 caractères, valeurs de 500 au plus), renvoyées telles quelles dans la session et les webhooks. En mode test, test_document_outcome et test_liveness_outcome choisissent le résultat simulé (voir Clés et modes).
allowed_document_types array<string> facultatif
Pièces acceptées : id_card (CNI), passport. Par défaut, les deux : l'usager choisit dans le SDK.
locale string facultatif
Langue du parcours affiché à l'usager. Valeurs : fr, en. (défaut : fr)
return_url url facultatif
Adresse vers laquelle la page de vérification renvoie l'usager à la fin du parcours.
En-têtes
Idempotency-Key string facultatif
Facultatif mais recommandé. Conservée 24 h : un appel rejoué avec la même clé et le même corps renvoie la même réponse (en-tête Idempotent-Replayed: true) et n'est facturé qu'une fois. 1 à 255 caractères.
Réponse : la session, avec en plus
client_secret string
Secret de la session, renvoyé une seule fois. Transmettez-le à votre front pour ouvrir le SDK ; il n'ouvre que cette session.
url string
Adresse de la page de vérification hébergée, à ouvrir directement si vous n'utilisez pas checkid.js.
Cycle de vie
created → document_pending → document_processing → challenge_pending → liveness_processing → verified | rejected | manual_review
Depuis tout état d'attente, la session peut passer à expired (30 minutes sans activité de l'usager) ou canceled. Détails dans Sessions et états.
Erreurs
| 402 | insufficient_funds | Le solde disponible ne couvre pas le prix de la session (mode live). La session n'est pas créée. |
| 400 | invalid_idempotency_key | Idempotency-Key vide ou trop longue. |
| 409 | idempotency_request_in_progress | Une requête avec la même Idempotency-Key est en cours. |
| 422 | idempotency_key_reused | La même Idempotency-Key a servi pour un corps différent. |
| 422 | invalid_request | Un paramètre est absent ou mal formé ; voir le champ param. |
| 401 | missing_api_key | En-tête Authorization absent. |
| 401 | invalid_api_key | Clé inconnue, révoquée, ou clé publique utilisée à la place de la clé secrète. |
| 403 | account_suspended | Compte suspendu : contactez CheckID. |
| 429 | rate_limited | Trop de requêtes pour cette clé ; réessayez après le délai de l'en-tête Retry-After. |
Format commun : voir Erreurs.
