> ## 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 d'ajout de visage : listes biométriques > Ajoutez un visage en base64 à une liste de blocage ou d'autorisation Didit. Didit en extrait la biométrie pour les futures correspondances faciales. Prompt de l'API d'ajout d'un visage à une liste Copier le prompt dans le presse-papiers \

\`Upload a face image directly to a Didit face blocklist or allowlist through the Management API.

Endpoint:
POST https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- Add a face to a face blocklist or allowlist when I do not have a verification session to reference. Didit detects the faces in the image, keeps the largest one, stores the image and a crop of that face, computes a biometric face template that new sessions are compared against, and creates the entry.
\- A face blocklist entry declines future sessions whose face matches. A face allowlist entry stops a matching face from triggering the duplicated-face action, but does not override blocklist matches or the other checks.

When NOT to use this:
\- If I am listing a face from an existing verification session, use POST /v3/lists/{list_uuid}/entries/ with reference_session_id instead, so the entry links back to the session.

Path parameter:
\- list_uuid: must be a list with entry_type "face" and list_type "blocklist" or "allowlist". Other lists return 400.

Request body (application/json):
\{
"image": "/9j/4AAQSkZ...",        // required: base64-encoded JPEG or PNG, at most 2 MB once decoded. Do not include a "data:image/..." prefix.
"comment": "Known fraud attempt"  // optional
}

Important constraints:
\- The image must show a clearly visible face. If no face is detected, the API returns 400 and no entry is created. If it shows several faces, Didit uses the largest one.
\- In a sandbox application the image is not analysed or stored: the entry has display_label "Sandbox face entry" and metadata.sandbox true, and matches nothing.

Example call:
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"image": "/9j/4AAQSkZ...", "comment": "Known fraud attempt"}'

Example response (201):
\{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"value": "44444444-5555-6666-7777-888888888888",
"display_label": "Manually uploaded face",
"comment": "Known fraud attempt",
"added_by": "api",
"reference_session_id": null,
"reference_session_number": null,
"reference_session_type": null,
"reference_object_uuid": "44444444-5555-6666-7777-888888888888",
"metadata": { "reference_image_url": "https:///face_reference_image.jpg" },
"created_at": "2026-10-12T10:12:18.904467Z"
}

value and reference_object_uuid are the UUID of the new face. metadata.reference_image_url is a short-lived signed URL (null for a scoped key without media: read).

Failure modes:
\- 400: the list is not a face list ({ "detail": "Face upload is only available for face-type lists." }), the list is a custom face list, image is missing, larger than 2 MB, not valid base64, not a readable JPEG or PNG, or shows no face ({ "image": "No face detected in the image. Please upload a clear photo with a visible face." }).
\- 401: the API key has expired.
\- 403: missing x-api-key (a wrong, revoked or expired key gets 401) ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows: write.
\- 404: list not found in this application ({ "detail": "List not found." }).
\- 503: face analysis is temporarily unavailable; no entry was created, retry later.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- The face template is added to biometric matching. Future sessions matching a blocklisted face are declined. Future sessions matching an allowlisted face skip the duplicated-face action and include an informational allowlist warning.

For the full integration shape, see /integration/integration-prompt.`

\
Coller dans Importez une image de visage encodée en base64 dans une liste de blocage ou d'autorisation faciale. Didit détecte les visages présents dans l'image, conserve le plus grand, stocke l'image et un recadrage de ce visage, puis calcule le gabarit biométrique facial auquel les nouvelles sessions sont comparées. La valeur (`value`) de la nouvelle entrée est l'UUID de ce visage.Disponible uniquement pour les listes avec `entry_type: face` et `list_type: blocklist` ou `list_type: allowlist`.> [!TIP] > > Si vous souhaitez ajouter à une liste de blocage ou d'autorisation un visage **provenant d'une session existante**, utilisez plutôt [Créer une entrée](https://docs.didit.me/fr/management-api/lists/create-entry.md) avec `reference_session_id` : l'entrée renvoie à la session.> [!WARNING] > > L'image doit contenir un visage clairement visible et ne pas dépasser 2 Mo une fois décodée. Si aucun visage n'est détecté, la requête renvoie `400` et aucune entrée n'est créée. Si l'analyse faciale est temporairement indisponible, elle renvoie `503` : réessayez plus tard.Pour retirer le visage de la liste, [supprimez son entrée](https://docs.didit.me/fr/management-api/lists/delete-entry.md) : il ne correspondra plus aux nouvelles sessions. ## OpenAPI ````yaml fr/openapi-25.json POST /v3/lists/{list_uuid}/entries/face-upload/ 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/lists/{list_uuid}/entries/face-upload/: post: tags: - Lists summary: Téléverser un visage dans une liste description: >- Ajoute un visage à une liste de blocage ou à une liste d'autorisation de visages à partir d'une image JPEG ou PNG encodée en base64, lorsque vous n'avez pas de session de vérification à référencer. Didit détecte les visages dans l'image, utilise le plus grand et crée une entrée dont `value` et `reference_object_uuid` correspondent à l'UUID du nouveau visage. Un visage placé sur liste de blocage entraîne le refus des nouvelles sessions dont le visage correspond ; un visage placé sur liste d'autorisation ignore l'action liée aux visages dupliqués et ne prévaut jamais sur une correspondance avec une liste de blocage. Dans une application sandbox, l'image n'est pas analysée et l'entrée ne correspond à aucun élément. Une clé API avec restriction de portée nécessite `workflows: write`. Pour ajouter un visage à partir d'une session existante, utilisez plutôt [Créer une entrée de liste](https://docs.didit.me/fr/management-api/lists/create-entry) avec `reference_session_id`. operationId: upload_list_entry_face parameters: - name: list_uuid in: path required: true description: >- UUID d'une liste avec `entry_type: face` et `list_type: blocklist` ou `allowlist`. schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- JPEG ou PNG encodé en Base64, d'au plus 2 Mo une fois décodé, montrant un visage clairement visible. Envoyez la chaîne base64 brute, sans préfixe `data:image/...;base64,`. comment: type: string default: '' description: >- Note en texte libre optionnelle, telle que le motif de l'inscription sur la liste. examples: Face image: value: image: /9j/4AAQSkZJRgABAQAAAQABAAD... comment: Known fraud attempt responses: '201': description: L'entrée faciale a été créée. content: application/json: schema: $ref: '#/components/schemas/ComplianceListEntry' examples: Uploaded face: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Manually uploaded face comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: reference_image_url: >- https://media.example.com/faces/reference.jpg?expires=1760263938&signature=3f9a1c created_at: '2026-10-12T10:12:18.904467Z' Sandbox application: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Sandbox face entry comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: sandbox: true created_at: '2026-10-12T10:12:18.904467Z' '400': description: >- La liste n'accepte pas les téléversements de visages, ou l'image est manquante, invalide, trop volumineuse ou ne présente aucun visage exploitable. Aucune entrée n'a été créée. content: application/json: examples: Not a face list: value: detail: Face upload is only available for face-type lists. Custom face list: value: detail: >- Face upload is only available for face blocklists and allowlists. Missing image: value: image: - This field is required. Invalid base64: value: image: - Invalid base64 encoding. Too large: value: image: - Image exceeds maximum size of 2 MB. Unreadable image: value: image: Invalid image. Provide a valid base64-encoded JPG or PNG. No face: value: image: >- No face detected in the image. Please upload a clear photo with a visible face. No usable face: value: image: Could not extract face embedding. Try a different image. '401': description: >- La clé API restreinte a expiré. Les autres échecs d'authentification renvoient `403`. content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- L'en-tête `x-api-key` est manquant (une clé incorrecte, révoquée ou expirée renvoie `401`), ou une clé API restreinte n'a pas l'autorisation `workflows: write` ou est utilisée depuis une adresse IP hors de sa liste d'autorisation. content: application/json: examples: Missing or invalid API key: value: detail: You do not have permission to perform this action. Scoped key without workflows access: value: detail: This API key has no write access to workflows. '404': description: >- Aucune liste avec cet UUID n'existe dans l'application de la clé API, ou elle a été supprimée. content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: >- L'analyse faciale est temporairement indisponible. Aucune entrée n'a été créée ; réessayez plus tard. content: application/json: examples: Unavailable: value: detail: Service temporarily unavailable. Please try again later. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/face-upload/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d "{\"image\": \"$(base64 < face.jpg | tr -d '\n')\", \"comment\": \"Known fraud attempt\"}" - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image="/9j/4AAQSkZJRgABAQAAAQABAAD...", comment="Known fraud attempt", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.lists.entries.uploadFace("11111111-2222-3333-4444-555555555555", { image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n\tComment: didit.String(\"Known fraud attempt\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.ListsEntriesUploadFaceParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.lists().entries().uploadFace("11111111-2222-3333-4444-555555555555", ListsEntriesUploadFaceParams.builder() .image("/9j/4AAQSkZJRgABAQAAAQABAAD...") .comment("Known fraud attempt") .build()); System.out.println(result); - lang: php label: PHP source: >- lists->entries->uploadFace('11111111-2222-3333-4444-555555555555', [ 'image' => '/9j/4AAQSkZJRgABAQAAAQABAAD...', 'comment' => 'Known fraud attempt', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Lists.Entries.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesUploadFaceParams { Image = "/9j/4AAQSkZJRgABAQAAAQABAAD...", Comment = "Known fraud attempt", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: ComplianceListEntry: type: object description: Une valeur dans une liste. required: - uuid - value - display_label - comment - added_by - reference_session_id - reference_session_number - reference_session_type - reference_object_uuid - metadata - created_at properties: uuid: type: string format: uuid description: >- Identifiant d'entrée. Utilisez-le comme `entry_uuid` dans Supprimer une entrée de liste. value: type: string description: "La valeur répertoriée\_: un numéro de téléphone au format E.164, une adresse e-mail, un numéro de document, une adresse IP ou une plage CIDR, une empreinte d'appareil, une adresse, un compte bancaire, un code pays ISO 3166-1 alpha-3, une `vendor_data`, toute chaîne de caractères sur une liste de type `key`, ou l'UUID du visage enregistré sur une liste de visages. Les valeurs que vous envoyez sont stockées en minuscules, à l'exception des numéros de téléphone et des codes pays. La recherche de correspondance est insensible à la casse." display_label: type: string nullable: true maxLength: 512 description: >- Libellé lisible par l'humain. Didit le renseigne pour les entrées issues d'une session (par exemple le nom du titulaire et le numéro de document) lorsque vous n'en transmettez aucun. comment: type: string description: Note en texte libre. Chaîne vide lorsqu'elle n'est pas définie. added_by: type: string nullable: true description: >- Qui a ajouté l'entrée : `api` (une clé API), l'adresse e-mail d'un utilisateur de la console ou `console`, `system` ou `migration` (entrées créées par Didit), ou `rule` (une action de règle de transaction ou de surveillance). reference_session_id: type: string format: uuid nullable: true description: >- Session de vérification dont provient l'entrée. `null` lorsque l'entrée a été ajoutée par valeur. reference_session_number: type: integer nullable: true description: >- Numéro de cette session propre à l'application, tel qu'affiché dans la console. reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: >- `kyc` pour une session de vérification de personne, `kyb` pour une session de vérification d'entreprise, `null` lorsqu'il n'y a pas de session. reference_object_uuid: type: string format: uuid nullable: true description: >- L'enregistrement que l'entrée représente : l'enregistrement de visage, de document, de téléphone ou d'e-mail lu à partir d'une session, le visage créé par Charger un visage dans une liste, ou l'UUID que vous avez envoyé (par exemple un UUID de transaction ou le `didit_internal_id` d'un utilisateur). metadata: type: object nullable: true additionalProperties: true description: >- Contexte supplémentaire. Contient les clés définies par Didit (listées ici) fusionnées avec les `metadata` que vous avez envoyées lors de la création de l'entrée, renvoyées telles quelles. `null` lorsqu'il n'y en a pas. properties: reference_image_url: type: string description: >- Entrées faciales : URL signée à courte durée de vie, réémise à chaque appel ; `null` pour une clé API restreinte sans `media: read`. Absent lorsqu'aucune image n'est associée à l'entrée. front_image_url: type: string description: >- Entrées de documents comportant une image du recto du document : URL signée de courte durée, réémise à chaque appel ; `null` pour une clé API restreinte sans `media: read`. full_name: type: string description: >- Entrées de documents issues d'une session : nom complet du titulaire. issuing_state: type: string description: >- Entrées de documents issues d'une session : pays de délivrance ISO 3166-1 alpha-3. document_type: type: string description: >- Entrées de documents issues d'une session : code du type de document, par exemple `P`, `ID` ou `DL`. region: type: string description: >- Entrées de documents issues d'une session : État ou province de délivrance pour un document émis au niveau régional, vide si non applicable. Non défini par l'ajout d'éléments de session à la liste de blocage. document_number: type: string description: 'Entrées de documents issues d''une session : numéro du document.' face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: >- Entrées faciales issues d'un selfie de capture de document : identifiant du selfie. Absent pour les visages de détection du vivant. reference_node_id: type: string nullable: true description: >- Entrées faciales issues d'un selfie de capture de document : le nœud de Vérification d'identité dont provient le selfie. fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: "Entrées d'empreinte d'appareil provenant d'une session\_: mode de dérivation de l'empreinte. `persistent_id` identifie un appareil\_; `composite_hash` et `legacy_fp` peuvent être partagés par des appareils du même modèle." sandbox: type: boolean description: >- `true` pour une entrée faciale téléversée dans une application sandbox ; une telle entrée ne correspond à aucun élément. reference_type: type: string enum: - transaction - vendor_user - vendor_business description: >- Défini par vous : élément vers lequel pointe `reference_object_uuid`, afin que la console puisse créer un lien vers celui-ci. reference_id: type: string description: 'Défini par vous : identifiant de l''enregistrement source.' created_at: type: string format: date-time description: Date et heure d'ajout de l'entrée. responses: RateLimitedWrite: description: >- La limite d'écriture partagée de 300 requêtes par minute et par clé API a été dépassée. Respectez l'en-tête `Retry-After` avant de réessayer. content: application/json: schema: type: object required: - detail properties: detail: type: string example: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. 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.