> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API Correspondance faciale : comparaison 1:1 > POST /v3/face-match/ : comparaison faciale 1:1 avec Didit. Vérification d'identité. Inférence sous 2s, tarif à l'usage, sans minimum mensuel. ## OpenAPI ````yaml fr/openapi-25.json POST /v3/face-match/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-match/: post: tags: - Standalone APIs summary: Correspondance faciale description: "Compare deux images faciales (1:1) et renvoie un `score` de similarité (0–100) ainsi qu'un `status` `Approved`/`Declined`.\n\n**Fonctionnement.** Les deux images sont décodées et analysées par un modèle biométrique (définissez `rotate_image=true` si les captures peuvent être de biais ou inversées), puis un score de similarité entre les deux visages est calculé. Un score **strictement supérieur** à `face_match_score_decline_threshold` (par défaut `30`) renvoie `status: \"Approved\"`\_; un score inférieur ou égal renvoie `Declined` avec un avertissement `LOW_FACE_MATCH_SIMILARITY`. Si aucune paire de visages ne peut être évaluée, l'appel renvoie tout de même `200` avec `status: \"Declined\"` et un avertissement `NO_REFERENCE_IMAGE` — `score` est `null` sur le chemin d'enregistrement par défaut, ou `0` avec `save_api_request=false`. Soumettez un visage net et de face par image pour de meilleurs résultats.\n\n**Facturation.** Chaque réponse `200` consomme un crédit d'API Face Match (débité de votre crédit de forfait ou de votre solde de recharge). Lorsque le solde de l'organisation ne peut pas couvrir l'appel, l'endpoint renvoie `403` avec l'erreur de crédits insuffisants avant tout traitement d'image.\n\n**Persistance de la session (`save_api_request`, par défaut `true`).** Lorsqu'il vaut `true`, l'appel est conservé sous forme de session de type API\_: il apparaît dans la Business Console, le `request_id` renvoyé est un véritable identifiant de session que vous pouvez passer à `GET /v3/session/{sessionId}/decision/`, les deux images sont stockées en tant qu'images source/cible de correspondance faciale de la session, et un webhook `status.updated` est émis vers vos destinations de webhook configurées. Lorsqu'il vaut `false`, rien n'est stocké et `request_id` est un UUID de corrélation à usage unique qui ne peut pas être consulté ultérieurement.\n\n**Index de recherche faciale.** Cet endpoint n'enrôle jamais de visages dans votre index de recherche faciale et n'exécute jamais de filtrage de liste de blocage ou de doublons — utilisez `POST /v3/passive-liveness/` ou `POST /v3/face-search/` pour cela.\n\n**Sandbox.** Les clés API de sandbox ignorent tout traitement et toute facturation\_: après validation de la requête (une entrée malformée renvoie toujours `400`), l'endpoint renvoie un payload fictif statique `Approved`, aucune session n'est conservée et aucun crédit n'est consommé.\n\n**Authentification.** Envoyez la clé API de votre application dans l'en-tête `x-api-key`. Des identifiants manquants ou non valides renvoient `403` (`{\"detail\": \"You do not have permission to perform this action.\"}`) — cette API ne renvoie jamais `401`.\n\n**Limite de débit.** Budget d'écriture partagé de 300 requêtes/min par clé API sur l'ensemble des endpoints POST/PATCH/DELETE\_; le dépasser renvoie `429`." operationId: post_v3face-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- Image d'un visage vivant ou d'un visage candidat à vérifier (p. ex. un selfie). Soumettez une seule photo de face avec le visage du sujet clairement visible et bien éclairé. Extensions autorisées : `tiff`, `jpg`, `jpeg`, `png`, `webp`. Taille maximale de téléversement : **5 MB** (les fichiers plus volumineux sont rejetés avec `400`). Les images sont automatiquement compressées à environ 0,5 MB avant le traitement, de sorte que des résolutions très élevées n'améliorent pas la précision. ref_image: type: string format: binary description: >- Image faciale de référence à comparer (par ex. un portrait de pièce d'identité ou une photo enregistrée au préalable). Même format et mêmes limites de taille que pour `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Seuil de similarité (0–100) qui détermine le `status` de la réponse. Un score calculé **inférieur ou égal** à cette valeur définit `status` sur `Declined` et ajoute un avertissement `LOW_FACE_MATCH_SIMILARITY` ; un score strictement supérieur renvoie `Approved`. La valeur par défaut de `30` est permissive — augmentez-la (par ex. `50`–`60`) pour une vérification plus stricte. Les valeurs en dehors de 0–100 renvoient `400`. example: 50 rotate_image: type: boolean default: false description: >- Lorsque la valeur est `true`, le service teste les images fournies par incréments de 90 degrés (0, 90, 180, 270) et utilise l'orientation qui produit la meilleure détection faciale — utile pour les captures mobiles sans orientation EXIF. Ajoute de la latence, ne l'activez donc que si vous ne pouvez pas garantir des images dans le bon sens. example: false save_api_request: type: boolean default: true description: >- Lorsque la valeur est `true` (par défaut), conserve l'appel sous la forme d'une session de type API — visible dans la Business Console, récupérable via `GET /v3/session/{sessionId}/decision/` à l'aide du `request_id` renvoyé, et notifiée via un webhook `status.updated`. Lorsque la valeur est `false`, rien n'est stocké et `request_id` est un UUID éphémère servant uniquement à la corrélation des réponses. example: true vendor_data: type: string description: >- Chaîne opaque optionnelle (votre identifiant d'utilisateur interne, e-mail, UUID…) stockée sur la session persistée et renvoyée dans la réponse. Utilisez-la pour corréler les appels d'API avec vos propres enregistrements et pour filtrer les sessions ultérieurement. example: user-123 metadata: type: object additionalProperties: true description: >- Objet JSON optionnel stocké avec la session (lorsque `save_api_request=true`) et renvoyé dans la réponse. Dans les requêtes multipart, envoyez-le sous forme de champ textuel encodé en JSON (par ex. `metadata={"flow":"login"}`) — il est analysé sous forme d'objet. example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- Correspondance faciale calculée. `face_match.score` est un nombre flottant compris entre 0 et 100 (deux décimales) ; `status` est `Approved` lorsque le score est strictement supérieur à `face_match_score_decline_threshold`, sinon `Declined` avec un avertissement explicatif. Une faible similarité ou une paire non évaluable renvoie toujours `200` — inspectez `face_match.status` et `face_match.warnings`, pas seulement le code HTTP. Lorsque `save_api_request=true`, `request_id` est l'identifiant de la session conservée. content: application/json: examples: Approved: summary: Même personne — score supérieur au seuil value: request_id: f9f5a777-8002-44c6-baaf-128bcfd6e226 face_match: status: Approved score: 99.41 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: Score inférieur ou égal au seuil de refus value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error short_description: Low face match similarity long_description: >- The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+00:00' schema: type: object properties: request_id: type: string format: uuid description: "Identifiant de session persistante lorsque `save_api_request=true` (utilisable avec `GET /v3/session/{sessionId}/decision/`)\_; sinon un UUID de corrélation temporaire." face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` lorsque le score de similarité est strictement supérieur à `face_match_score_decline_threshold` et qu'un score a pu être calculé ; `Declined` dans le cas contraire (un avertissement en explique la raison). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Score de similarité de 0 à 100 — niveau de confiance du modèle quant au fait que les deux images représentent la même personne. Arrondi à deux décimales uniquement lorsque `save_api_request` est défini sur true ; avec `save_api_request=false`, le nombre à virgule flottante brut est renvoyé. `null` lorsqu'aucune paire de visages n'a pu être notée (avec `save_api_request=true` par défaut) ; avec `save_api_request=false`, cette même situation peut apparaître sous la forme `score: 0`. Dans les deux cas, un avertissement `NO_REFERENCE_IMAGE` est présent et `status` est `Declined`. example: 99.41 user_image: type: object description: >- Résultats de la détection faciale pour les images analysées. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Boîte englobante du visage détecté sous forme de coordonnées en pixels `[x_min, y_min, x_max, y_max]` dans l'image traitée. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: >- Indice de confiance de la détection faciale (0–1). example: 0.732973 age: type: number format: float description: >- Âge estimé par le modèle pour le visage détecté, en années. À titre informatif uniquement — n'affecte pas la décision de correspondance faciale. example: 26.91 gender: type: string description: >- Genre prédit par le modèle pour le visage détecté (`male` ou `female`). À titre informatif uniquement. example: male race: type: string nullable: true description: >- Champ réservé — toujours `null` dans les réponses de cet endpoint. example: null description: Une entrée par visage détecté. best_angle: type: integer description: >- Rotation (en degrés : 0, 90, 180 ou 270) ayant produit la meilleure détection de visage. Non nulle uniquement lorsque `rotate_image=true` a corrigé l'orientation. example: 0 ref_image: type: object description: >- Résultats de la détection faciale pour l'image de référence, même format que `user_image`. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Boîte englobante du visage détecté sous forme de coordonnées en pixels `[x_min, y_min, x_max, y_max]` dans l'image traitée. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: >- Indice de confiance de la détection faciale (0–1). example: 0.732973 age: type: number format: float description: >- Âge estimé par le modèle pour le visage détecté, en années. À titre informatif uniquement — n'affecte pas la décision de correspondance faciale. example: 26.91 gender: type: string description: >- Genre prédit par le modèle pour le visage détecté (`male` ou `female`). À titre informatif uniquement. example: male race: type: string nullable: true description: >- Champ réservé — toujours `null` dans les réponses de cet endpoint. example: null description: Une entrée par visage détecté. best_angle: type: integer example: 0 warnings: type: array description: >- Vide en cas d'approbation sans réserve. `NO_REFERENCE_IMAGE` (`error`) — aucune paire de visages n'a pu être évaluée ; `LOW_FACE_MATCH_SIMILARITY` (`error`) — score inférieur ou égal au seuil de refus. N'importe lequel d'entre eux définit `status` sur `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: Code de risque lisible par machine. feature: type: string enum: - FACEMATCH description: >- Fonctionnalité ayant émis l'avertissement. Toujours `FACEMATCH` sur cet endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Toujours `null` pour les avertissements de correspondance faciale. log_type: type: string enum: - error - warning - information description: >- Gravité. Les avertissements `error` font passer `status` à `Declined` ; les entrées `warning` et `information` sont indicatives et ne refusent jamais d'elles-mêmes. short_description: type: string description: >- Résumé du risque en une ligne, lisible par l'utilisateur. long_description: type: string description: Explication lisible par l'humain du risque. vendor_data: type: string nullable: true description: Écho des `vendor_data` que vous avez envoyées, ou `null`. metadata: type: object nullable: true additionalProperties: true description: >- Écho de l'objet `metadata` que vous avez envoyé, ou `null`. created_at: type: string format: date-time description: >- Horodatage ISO 8601 (UTC) du moment où la réponse a été générée, ex. `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Erreur de validation. Renvoyée lorsqu'une image requise est manquante, dépasse 5 Mo, possède une extension non prise en charge, ou lorsqu'une option est hors limites. Le corps est l'enveloppe standard d'erreur de champ de DRF : un tableau de messages par champ en cause. content: application/json: examples: Missing required image: summary: >- `ref_image` (ou `user_image`) non inclus dans les données de formulaire value: ref_image: - No file was submitted. Unsupported file extension: summary: Extension de fichier autre que tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: Le téléversement dépasse la limite de 5 MB value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_match_score_decline_threshold` hors de 0–100' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: "Permission refusée. Renvoyé lorsque l'en-tête `x-api-key` est manquant, ainsi que lorsque le solde de l'organisation appelante ne permet pas de couvrir l'appel\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Une clé manquante renvoie `403` avec `{\"detail\": ...}`\_; une clé incorrecte, révoquée ou expirée renvoie `401`. Les crédits insuffisants renvoient `403` avec `{\"error\": ...}` avant tout traitement d'image." content: application/json: examples: Missing or invalid API key: summary: Aucun en-tête `x-api-key`, ou la clé est non valide/révoquée value: detail: You do not have permission to perform this action. Not enough credits: summary: Le solde de l'organisation ne peut pas couvrir l'appel value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de débit dépassée. Les endpoints POST/PATCH/DELETE partagent un budget de 300 requêtes d'écriture par minute par clé API (la création de transactions et l'ingestion d'événements ont un budget distinct de 600). La réponse comporte les en-têtes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` et `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: >- Plus de 300 requêtes d'écriture au cours de la minute actuelle value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.