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).
external_id string obligatoire
Votre identifiant unique de cette requête dans votre base (une commande, une demande d'ouverture de compte…). Unique par mode : une seconde session avec le même external_id est refusée (409 external_id_taken). Renvoyé dans la session, les webhooks et les rappels ; permet de lire la session avec GET /v1/sessions/external/{external_id}. Lettres, chiffres et . _ : @ -. (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.
callback_url url facultatif
Adresse de votre serveur qui reçoit le statut final de cette session (vérifiée, rejetée, en revue manuelle puis décision de la revue, expirée, annulée), signé avec le secret des URL de rappel (voir Webhooks et rappels). https obligatoire en production.
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. |
| 409 | external_id_taken | Une session existe déjà avec cet external_id dans ce mode ; son id est dans le champ session_id de l'erreur. |
| 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.
