API de gestion Didit v3 : workflows et facturation

Authentification

Tous les endpoints de l’API de gestion utilisent votre clé API d’application. Aucun UUID d’organisation ou d’application n’est nécessaire dans les URL : l’application est identifiée à partir de votre clé.

curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...

Vous n’avez pas encore de clé API ? Inscrivez-vous de manière programmatique en deux appels d’API.

Workflows

Les workflows définissent les étapes de vérification que vos utilisateurs doivent suivre (scan de pièce d’identité, détection du vivant, correspondance faciale, filtrage AML, etc.). Chaque workflow est une configuration réutilisable que vous associez aux sessions.

GET

Liste tous les workflows de votre application. Renvoie les fonctionnalités et les seuils de chaque workflow, et indique lequel est le workflow par défaut.

POST

Crée un nouveau workflow. Définissez les fonctionnalités de vérification à activer, réglez les seuils, configurez les types de documents acceptés, et bien plus encore.

GET

Récupère le détail complet d’un workflow spécifique, y compris toutes les configurations de fonctionnalités et tous les seuils.

PATCH

Met à jour la configuration d’un workflow. Vous pouvez modifier n’importe quel paramètre de fonctionnalité, seuil ou document accepté.

DELETE

Supprime un workflow. Les sessions qui utilisent déjà ce workflow ne sont pas affectées.

Nous recommandons vivement d’utiliser la Console Business pour créer et configurer les workflows. Le constructeur visuel de workflows propose des modèles, une configuration des fonctionnalités par glisser-déposer, les paramètres des documents, le réglage des seuils et un aperçu, le tout sans écrire de code. N’utilisez l’API que pour l’automatisation ou la gestion programmatique des workflows.

Exemple rapide de création d’un workflow

Le workflow_type détermine l’ensemble de fonctionnalités de base. Les fonctionnalités individuelles s’activent ensuite avec les indicateurs is_*_enabled.

curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'

Valeurs disponibles pour workflow_type : kyc, kyb, adaptive_age_verification, biometric_authentication, address_verification, questionnaire_verification, email_verification, phone_verification. Pour les workflows kyc, la vérification d’identité est incluse automatiquement : vous n’avez pas besoin d’un indicateur distinct pour elle. Utilisez les indicateurs is_*_enabled pour ajouter ou retirer les fonctionnalités facultatives, comme la correspondance faciale, la détection du vivant, l’AML, le NFC, le téléphone, l’e-mail, le justificatif de domicile, l’analyse de l’appareil et de l’IP, et d’autres encore. Utilisez ensuite le workflow lors de la création des sessions :

curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'

Questionnaires

Formulaires personnalisés que vous pouvez ajouter aux workflows de vérification pour collecter des informations supplémentaires auprès des utilisateurs.

GET

Liste tous les questionnaires.

POST

Crée un nouveau questionnaire avec des questions personnalisées, une logique conditionnelle et des traductions.

GET

Récupère le détail d’un questionnaire, y compris toutes les questions et la structure du formulaire.

PATCH

Met à jour un questionnaire.

DELETE

Supprime un questionnaire.

Utilisateurs

Gérez les personnes vérifiées (utilisateurs) de votre application. Chaque utilisateur est identifié par une chaîne vendor_data que vous fournissez lors de la création des sessions.

GET

Liste tous les utilisateurs de votre application, y compris leur statut de vérification et leur historique de sessions.

GET

Récupère le détail d’un utilisateur à partir de votre identifiant vendor_data.

PATCH

Met à jour les métadonnées d’un utilisateur.

POST

Supprime des utilisateurs en lot. Corps : {"vendor_data_list": ["user-1", "user-2"]} ou {"delete_all": true}. Purge aussi tous les gabarits biométriques conservés pour ces utilisateurs.

Gabarits biométriques

Gabarits biométriques faciaux sans image qu’une application ayant opté pour cette conservation garde après la suppression des sessions. Voir Gabarits biométriques.

GET

Liste paginée avec filtres (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to, ordering).

GET

Nombre de gabarits, avec les mêmes filtres.

GET

Un gabarit : l’utilisateur propriétaire, la référence de provenance, la date d’expiration, l’instruction et le statut.

DELETE

Purge un gabarit. Renvoie {"uuid": "...", "outcome": "purged" | "already_purged"}.

POST

Purge en masse. Corps : {"template_uuids": [...]} ou {"delete_all": true}, avec des filtres facultatifs.

Opérations sur les sessions

POST

Supprime des sessions en lot. Nécessite delete:sessions. Corps : {"session_numbers": ["1", "2", "3"]} ou {"delete_all": true} (pour restreindre delete_all, utilisez les filtres de la liste des sessions préfixés par filter_, comme filter_status), ainsi que les paramètres facultatifs retain_face_embeddings, face_retention_days, face_retention_deadline, deletion_instruction et instruction_id. Jusqu’à 20 sessions correspondantes renvoient 200 avec un face_retention_outcome par session ; au-delà, la réponse est 202 avec un job de suppression.

GET

Progression et décompte des résultats d’une suppression en lot de sessions ayant renvoyé 202.

GET

Répertorie les examens et le journal d’activité d’une session.

POST

Ajoute une note d’examen ou modifie le statut d’une session.

Facturation

GET

Obtenir le solde de crédits actuel et les paramètres de recharge automatique.

{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}

POST

Créer une session de paiement Stripe pour recharger des crédits. Chaque recharge est comprise entre $50 et $20,000 et ajoutée à sa valeur faciale.

{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}

Listes (listes de blocage, listes d’autorisation et listes personnalisées)

Gérez les listes typées pour le blocage, l’autorisation et les conditions de workflow personnalisées. Consultez la documentation complète de l’API Lists.

GET

Lister toutes les listes de l’application (listes de blocage, listes d’autorisation, listes personnalisées).

POST

Ajouter une entrée à une liste. Prend en charge reference_session_id pour extraire automatiquement les données d’une session, et reference_object_uuid pour la traçabilité vers les transactions, les utilisateurs ou les entreprises.

DELETE

Supprimer une entrée d’une liste.

POST

Importer une image de visage dans une liste de blocage de visages (base64).

Configuration du webhook

GET

Obtenir la configuration actuelle du webhook, y compris l’URL, la version, la clé secrète permettant de vérifier les signatures des webhooks, et la politique de conservation des données et des gabarits biométriques de l’application. La réponse contient aussi allowed_domains, décrit sous PATCH /v3/webhook/ ci-dessous.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"],
  "allowed_domains": ["https://app.example.com"]
}

PATCH

Mettre à jour l’URL et la version du webhook, ou renouveler la clé secrète. Définissez rotate_secret_key: true pour générer un nouveau secret de webhook (l’ancien est immédiatement invalidé). Définit aussi la politique de conservation de l’application : data_retention_months, et face_retention_policy (delete_with_session par défaut, ou retain_until_user_deleted), accompagné d’une valeur face_retention_days finie et obligatoire (1-3650) lorsque la conservation est activée. Voir Conservation des gabarits biométriques. Enregistre également allowed_return_hosts : jusqu’à 20 noms d’hôte seuls (par exemple app.example.com, sans schéma, port, chemin ni caractère générique) vers lesquels une vérification effectuée via l’API de portefeuille Digital ID peut renvoyer la personne en HTTPS. Une nouvelle liste remplace la liste enregistrée, et le domaine en marque blanche de votre application est toujours autorisé.Définit également allowed_domains : jusqu’à 50 origines web (par exemple https://app.example.com) dans lesquelles le parcours de vérification hébergé peut être intégré et vers lesquelles il peut renvoyer l’utilisateur avec un callback de session. Chaque entrée se compose d’un schéma, d’un hôte et d’un port facultatif, sans chemin, sans requête ni caractère générique. Utilisez https ; http n’est accepté que pour localhost, 127.0.0.1 et ::1. Didit enregistre chaque origine en minuscules, sans port par défaut, et renvoie la liste dans allowed_domains. Une entrée non valide entraîne une erreur 400 pour allowed_domains. Une nouvelle liste remplace la liste enregistrée, et une liste vide supprime la restriction. Tant que la liste n’est pas vide, POST /v3/session/ rejette avec une erreur 400 tout callback web qui n’y figure pas, et le parcours hébergé ne redirige pas l’utilisateur vers un callback enregistré ou défini par défaut dans le workflow qui n’y figure pas. Les schémas d’URL personnalisés (liens profonds d’application) et les appels d’API serveur à serveur ne sont pas concernés.Si vous envoyez endpoints, chaque destination de webhook absente de la liste est supprimée définitivement, avec son secret de signature et l’intégralité de son journal de livraison, exactement comme DELETE /v3/webhook/destinations/{destination_uuid}/. Cette action est irréversible. Pour gérer les destinations une par une, utilisez plutôt les endpoints de destination de webhook.

{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}

Récapitulatif complet des endpoints d’API

Endpoint	Méthode	Description
`/v3/session/`	POST	Créer une session de vérification
`/v3/sessions/`	GET	Lister toutes les sessions
`/v3/session/{id}/decision/`	GET	Obtenir le résultat de vérification de la session
`/v3/session/{id}/update-status/`	PATCH	Approuver ou refuser une session
`/v3/session/{id}/delete/`	DELETE	Supprimer une session
`/v3/sessions/delete/`	POST	Supprimer des sessions par lot
`/v3/sessions/delete/{job_id}/`	GET	Statut de la tâche de suppression de sessions en masse
`/v3/sessions/{id}/reviews/`	GET, POST	Activité et examens de la session
`/v3/workflows/`	GET, POST	Lister / créer des workflows
`/v3/workflows/{id}/`	GET, PATCH, DELETE	Détail / mise à jour / suppression d’un workflow
`/v3/questionnaires/`	GET, POST	Lister / créer des questionnaires
`/v3/questionnaires/{id}/`	GET, PATCH, DELETE	Détail d’un questionnaire
`/v3/users/`	GET	Lister les utilisateurs vérifiés
`/v3/users/{vendor_data}/`	GET, PATCH	Détail / mise à jour d’un utilisateur
`/v3/users/delete/`	POST	Supprimer des utilisateurs par lot (purge aussi leurs gabarits biométriques conservés)
`/v3/biometric-templates/`	GET	Lister les gabarits biométriques conservés
`/v3/biometric-templates/count/`	GET	Compter les gabarits biométriques conservés
`/v3/biometric-templates/{id}/`	GET, DELETE	Détail / purge d’un gabarit
`/v3/biometric-templates/delete/`	POST	Purger les gabarits en masse
`/v3/lists/`	GET, POST	Lister toutes les listes / créer une liste
`/v3/lists/{id}/`	GET, PATCH, DELETE	Détail / mise à jour / suppression d’une liste
`/v3/lists/{id}/entries/`	GET, POST	Lister les entrées / ajouter une entrée
`/v3/lists/{id}/entries/{eid}/`	DELETE	Supprimer une entrée
`/v3/lists/{id}/entries/face-upload/`	POST	Importer un visage dans la liste de blocage
`/v3/webhook/`	GET, PATCH	Configuration du webhook (URL, secret, version), politique de conservation et hôtes de retour du portefeuille
`/v3/billing/balance/`	GET	Consulter le solde de crédits
`/v3/billing/top-up/`	POST	Recharger les crédits

Dernière modification le 7 novembre 2026

​Authentification

​Workflows

​Exemple rapide de création d’un workflow

​Questionnaires

​Utilisateurs

​Gabarits biométriques

​Opérations sur les sessions

​Facturation

​Listes (listes de blocage, listes d’autorisation et listes personnalisées)

​Configuration du webhook

​Récapitulatif complet des endpoints d’API

Authentification

Workflows

Exemple rapide de création d’un workflow

Questionnaires

Utilisateurs

Gabarits biométriques

Opérations sur les sessions

Facturation

Listes (listes de blocage, listes d’autorisation et listes personnalisées)

Configuration du webhook

Récapitulatif complet des endpoints d’API