> ## 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 per pujar rostres: llistes biomètriques > Puja una imatge facial en base64 a una llista de bloqueig o de permesos de Didit, que l'usa en futures coincidències facials. Prompt de l'API per pujar una cara a la llista Copia el prompt al porta-retalls \

\`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.`

\
Enganxa a Puja una imatge facial codificada en base64 a una llista de bloqueig o de permesos de cares. Didit detecta les cares de la imatge, en conserva la més gran, emmagatzema la imatge i un retall d'aquesta cara, i calcula la plantilla biomètrica facial amb què es compararan les noves sessions. El `value` de la nova entrada és l'UUID d'aquesta cara.Només disponible per a llistes amb `entry_type: face` i `list_type: blocklist` o `list_type: allowlist`.> [!TIP] > > Si vols posar a la llista de bloqueig o de permesos una cara **d'una sessió existent**, fes servir [Crea una entrada](https://docs.didit.me/ca/management-api/lists/create-entry.md) amb `reference_session_id`: l'entrada queda enllaçada amb la sessió.> [!WARNING] > > La imatge ha de contenir una cara clarament visible i no pot superar els 2 MB una vegada descodificada. Si no es detecta cap cara, la sol·licitud retorna `400` i no es crea cap entrada. Si l'anàlisi facial no està disponible temporalment, retorna `503`: torna-ho a intentar més tard.Per eliminar la cara de la llista, [elimina'n l'entrada](https://docs.didit.me/ca/management-api/lists/delete-entry.md): la cara deixa de coincidir amb les noves sessions. ## OpenAPI ````yaml ca/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 verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/lists/{list_uuid}/entries/face-upload/: post: tags: - Lists summary: Puja una cara a una llista description: >- Afegeix una cara a una llista de bloqueig de cares o a una llista de cares admeses a partir d'una imatge JPEG o PNG codificada en base64, per a casos en què no tinguis cap sessió de verificació a la qual fer referència. Didit detecta les cares de la imatge, utilitza la més gran i crea una entrada el `value` i el `reference_object_uuid` de la qual són l'UUID de la cara nova. Una cara en una llista de bloqueig fa que es rebutgin noves sessions la cara de les quals coincideixi; una cara en una llista de cares admeses omet l'acció de cara duplicada i mai preval sobre una coincidència amb la llista de bloqueig. En una aplicació de sandbox la imatge no s'analitza i l'entrada no coincideix amb res. Una clau d'API amb àmbit necessita `workflows: write`. Per afegir a la llista una cara procedent d'una sessió existent, fes servir [Crear una entrada de llista](https://docs.didit.me/ca/management-api/lists/create-entry) amb `reference_session_id` en el seu lloc. operationId: upload_list_entry_face parameters: - name: list_uuid in: path required: true description: >- UUID d'una llista amb `entry_type: face` i `list_type: blocklist` o `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 o PNG codificat en base64, de 2 MB com a màxim un cop descodificat, que mostri una cara clarament visible. Envia la cadena base64 sola, sense el prefix `data:image/...;base64,`. comment: type: string default: '' description: >- Nota opcional en text lliure, com ara el motiu de la inclusió a la llista. examples: Face image: value: image: /9j/4AAQSkZJRgABAQAAAQABAAD... comment: Known fraud attempt responses: '201': description: L'entrada de cara s'ha creat. 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 llista no admet càrregues d'imatges facials, o la imatge no hi és, no és vàlida, és massa gran o no mostra cap cara utilitzable. No s'ha creat cap entrada. 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 clau d'API amb abast ha caducat. Altres fallades d'autenticació retornen `403`. content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- Falta la capçalera `x-api-key` (una clau incorrecta, revocada o caducada rep un `401`), o una clau d'API amb àmbit no té `workflows: write` o s'utilitza des d'una adreça IP fora de la seva llista d'admesos. 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: >- No existeix cap llista amb aquest UUID a l'aplicació de la clau d'API, o s'ha suprimit. content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: >- L'anàlisi facial no està disponible temporalment. No s'ha creat cap entrada; torna-ho a provar més 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: Un valor en una llista. 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: >- Identificador de l'entrada. Utilitza'l com a `entry_uuid` a l'operació «Eliminar una entrada de llista». value: type: string description: >- El valor llistat: un número de telèfon en E.164, una adreça de correu electrònic, un número de document, una adreça IP o rang CIDR, una empremta digital de dispositiu, una adreça de cartera, un compte bancari, un codi de país ISO 3166-1 alfa-3, un `vendor_data`, qualsevol cadena en una llista `key`, o l'UUID de la cara emmagatzemada en una llista de cares. Els valors que envies s'emmagatzemen en minúscules, excepte els números de telèfon i els codis de país. La coincidència no distingeix entre majúscules i minúscules. display_label: type: string nullable: true maxLength: 512 description: >- Etiqueta fàcil de llegir. Didit l'emplena per a entrades extretes d'una sessió (per exemple, el nom del titular i el número de document) quan no n'envies cap. comment: type: string description: Nota de text lliure. Cadena buida si no s'ha definit. added_by: type: string nullable: true description: >- Qui ha afegit l'entrada: `api` (una clau d'API), l'adreça de correu electrònic d'un usuari de la consola o `console`, `system` o `migration` (entrades creades per Didit) o `rule` (una acció de regla de transacció o de monitoratge). reference_session_id: type: string format: uuid nullable: true description: >- Sessió de verificació d'on s'ha extret l'entrada. `null` quan l'entrada s'ha afegit per valor. reference_session_number: type: integer nullable: true description: >- Número d'aquesta sessió en l'àmbit de l'aplicació, tal com es mostra a la consola. reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: >- `kyc` per a una sessió de verificació de persona, `kyb` per a una sessió de verificació d'empresa, `null` quan no hi ha cap sessió. reference_object_uuid: type: string format: uuid nullable: true description: >- El registre que representa l'entrada: el registre de rostre, document, telèfon o correu electrònic llegit d'una sessió, el rostre creat per Upload a face to a list, o l'UUID que has enviat (per exemple, un UUID de transacció o el `didit_internal_id` d'un usuari). metadata: type: object nullable: true additionalProperties: true description: >- Context addicional. Conté les claus que estableix Didit (llistades aquí) combinades amb qualsevol `metadata` que hagis enviat en crear l'entrada, retornades tal com s'han desat. `null` quan no n'hi ha cap. properties: reference_image_url: type: string description: >- Entrades facials: URL signada de curta durada, emesa de nou en cada crida; `null` per a una clau d'API amb un àmbit que no inclou `media: read`. Absent quan cap imatge pertany a l'entrada. front_image_url: type: string description: >- Entrades de document que contenen una imatge frontal del document: URL signat de curta durada, emès novament a cada crida; `null` per a una clau d'API amb abast limitat sense `media: read`. full_name: type: string description: >- Entrades de document obtingudes d'una sessió: nom complet del titular. issuing_state: type: string description: >- Entrades de document obtingudes d'una sessió: país emissor ISO 3166-1 alfa-3. document_type: type: string description: >- Entrades de document obtingudes d'una sessió: codi de tipus de document, per exemple `P`, `ID` o `DL`. region: type: string description: >- Entrades de document obtingudes d'una sessió: estat o província emissor d'un document emès regionalment, buit quan no correspongui. No s'estableix mitjançant Add session items to the blocklist. document_number: type: string description: >- Entrades de document obtingudes d'una sessió: el número de document. face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: >- Entrades facials obtingudes d'una selfie de captura de documents: quina selfie. No apareix per a cares de prova de vida. reference_node_id: type: string nullable: true description: >- Entrades facials obtingudes d'una selfie de captura de documents: el node de verificació d'identitat d'on prové la selfie. fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: >- Entrades de la petjada digital del dispositiu obtingudes d'una sessió: com es va derivar la petjada digital. `persistent_id` identifica un sol dispositiu; `composite_hash` i `legacy_fp` es poden compartir entre dispositius del mateix model. sandbox: type: boolean description: >- `true` en una entrada facial pujada en una aplicació sandbox; aquesta entrada no coincideix amb res. reference_type: type: string enum: - transaction - vendor_user - vendor_business description: >- Definit per tu: a què apunta `reference_object_uuid`, perquè la consola hi enllaci de tornada. reference_id: type: string description: 'Definit per tu: identificador del registre d''origen.' created_at: type: string format: date-time description: Quan es va afegir l'entrada. responses: RateLimitedWrite: description: >- S'ha superat el límit compartit d'escriptura de 300 sol·licituds per minut per clau d'API. Respecta `Retry-After` abans de reintentar. 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 clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.