> ## 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. # Gesicht hochladen API: Biometrische Listen > Base64-Gesichtsbild in eine Didit-Sperr- oder Erlaubnisliste hochladen. Didit nutzt das biometrische Template für künftige Gesichtsabgleiche. Prompt für die API zum Hochladen eines Gesichts in eine Liste Prompt in die Zwischenablage kopieren \

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

\
Einfügen in Laden Sie ein base64-kodiertes Gesichtsbild in eine Gesichts-Sperrliste oder Freigabeliste hoch. Didit erkennt die Gesichter im Bild, behält das größte davon, speichert das Bild und einen Zuschnitt dieses Gesichts und berechnet das biometrische Template des Gesichts, mit dem neue Sitzungen verglichen werden. Der `value` des neuen Eintrags ist die UUID dieses Gesichts.Nur verfügbar für Listen mit `entry_type: face` und `list_type: blocklist` oder `list_type: allowlist`.> [!TIP] > > Wenn Sie ein Gesicht aus einer **bestehenden Sitzung** auf die Sperrliste oder Freigabeliste setzen möchten, verwenden Sie stattdessen [Eintrag erstellen](https://docs.didit.me/de/management-api/lists/create-entry.md) mit `reference_session_id`. Der Eintrag verweist dann auf die Sitzung.> [!WARNING] > > Das Bild muss ein deutlich sichtbares Gesicht enthalten und nach der Dekodierung höchstens 2 MB groß sein. Wird kein Gesicht erkannt, gibt die Anfrage `400` zurück, und es wird kein Eintrag erstellt. Ist die Gesichtsanalyse vorübergehend nicht verfügbar, gibt sie `503` zurück: Versuchen Sie es später erneut.Um das Gesicht von der Liste zu entfernen, [löschen Sie dessen Eintrag](https://docs.didit.me/de/management-api/lists/delete-entry.md). Es gleicht dann keine neuen Sitzungen mehr ab. ## OpenAPI ````yaml de/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 für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/lists/{list_uuid}/entries/face-upload/: post: tags: - Lists summary: Gesicht in eine Liste hochladen description: >- Fügt ein Gesicht aus einem base64-kodierten JPEG- oder PNG-Bild zu einer Gesichts-Sperrliste oder Gesichts-Zulassungsliste hinzu, falls Sie keine Verifizierungssitzung als Referenz haben. Didit erkennt die Gesichter im Bild, verwendet das größte und erstellt einen Eintrag, dessen `value` und `reference_object_uuid` die UUID des neuen Gesichts sind. Ein Gesicht auf der Sperrliste lehnt neue Sitzungen ab, deren Gesicht übereinstimmt; ein Gesicht auf der Zulassungsliste überspringt die Aktion für duplizierte Gesichter und überschreibt niemals einen Sperrlistentreffer. In einer Sandbox-Anwendung wird das Bild nicht analysiert und der Eintrag stimmt mit nichts überein. Ein API-Schlüssel mit Berechtigungsbeschränkung erfordert `workflows: write`. Um ein Gesicht aus einer bestehenden Sitzung einer Liste hinzuzufügen, verwenden Sie stattdessen [Listeneintrag erstellen](https://docs.didit.me/de/management-api/lists/create-entry) mit `reference_session_id`. operationId: upload_list_entry_face parameters: - name: list_uuid in: path required: true description: >- UUID einer Liste mit `entry_type: face` und `list_type: blocklist` oder `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: >- Base64-kodiertes JPEG oder PNG, nach dem Dekodieren maximal 2 MB groß, das ein deutlich sichtbares Gesicht zeigt. Senden Sie die reine Base64-Zeichenfolge ohne das Präfix `data:image/...;base64,`. comment: type: string default: '' description: >- Optionale Freitextnotiz, wie beispielsweise der Grund für die Listung. examples: Face image: value: image: /9j/4AAQSkZJRgABAQAAAQABAAD... comment: Known fraud attempt responses: '201': description: Der Gesichtseintrag wurde erstellt. 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: >- Die Liste akzeptiert keine Gesichtsuploads oder das Bild fehlt, ist ungültig, zu groß oder zeigt kein verwertbares Gesicht. Es wurde kein Eintrag erstellt. 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: >- Der API-Schlüssel mit eingeschränktem Geltungsbereich ist abgelaufen. Andere Authentifizierungsfehler geben `403` zurück. content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- Der `x-api-key`-Header fehlt (ein falscher, widerrufener oder abgelaufener Schlüssel erhält `401`), oder ein API-Schlüssel mit Berechtigungseinschränkungen verfügt nicht über `workflows: write` oder wird von einer IP-Adresse außerhalb seiner Zulassungsliste verwendet. 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: >- In der Anwendung des API-Schlüssels existiert keine Liste mit dieser UUID, oder sie wurde gelöscht. content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: >- Die Gesichtsanalyse ist vorübergehend nicht verfügbar. Es wurde kein Eintrag erstellt; versuchen Sie es später erneut. 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: Ein Wert in einer 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: >- Eintrags-ID. Verwenden Sie sie als `entry_uuid` in „Listeneintrag löschen“. value: type: string description: >- Der gelistete Wert: eine Telefonnummer in E.164, eine E-Mail-Adresse, eine Dokumentennummer, eine IP-Adresse oder ein CIDR-Bereich, ein Geräte-Fingerprint, eine Wallet-Adresse, ein Bankkonto, ein Ländercode nach ISO 3166-1 Alpha-3, ein `vendor_data`, eine beliebige Zeichenfolge auf einer `key`-Liste oder die UUID des gespeicherten Gesichts auf einer Gesichtsliste. Von Ihnen gesendete Werte werden in Kleinbuchstaben gespeichert, mit Ausnahme von Telefonnummern und Ländercodes. Der Abgleich erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung. display_label: type: string nullable: true maxLength: 512 description: >- Lesbare Bezeichnung. Didit füllt sie für aus einer Sitzung übernommene Einträge aus (beispielsweise Name und Dokumentennummer des Inhabers), wenn Sie keine übermitteln. comment: type: string description: Freitext-Notiz. Leere Zeichenkette, wenn nicht festgelegt. added_by: type: string nullable: true description: >- Wer den Eintrag hinzugefügt hat: `api` (ein API-Schlüssel), die E-Mail-Adresse eines Benutzers der Konsole oder `console`, `system` oder `migration` (von Didit erstellte Einträge) oder `rule` (eine Transaktions- oder Überwachungsregel-Aktion). reference_session_id: type: string format: uuid nullable: true description: >- Verifizierungssitzung, aus der der Eintrag übernommen wurde. `null`, wenn der Eintrag als Wert hinzugefügt wurde. reference_session_number: type: integer nullable: true description: >- Nummer dieser Sitzung innerhalb der Anwendung, wie in der Console angezeigt. reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: >- `kyc` für eine Sitzung zur Personenverifizierung, `kyb` für eine Sitzung zur Unternehmensverifizierung, `null`, wenn keine Sitzung vorhanden ist. reference_object_uuid: type: string format: uuid nullable: true description: >- Der Datensatz, für den der Eintrag steht: der aus einer Sitzung gelesene Gesichts-, Dokumenten-, Telefon- oder E-Mail-Datensatz, das über Ein Gesicht zu einer Liste hochladen erstellte Gesicht oder die von Ihnen gesendete UUID (z. B. eine Transaktions-UUID oder die `didit_internal_id` eines Benutzers). metadata: type: object nullable: true additionalProperties: true description: >- Zusätzlicher Kontext. Enthält die von Didit festgelegten Schlüssel (hier aufgeführt), zusammengeführt mit allen `metadata`, die Sie beim Erstellen des Eintrags gesendet haben, zurückgegeben wie gespeichert. `null`, wenn keine vorhanden sind. properties: reference_image_url: type: string description: >- Gesichtseinträge: kurzlebige signierte URL, die bei jedem Aufruf neu ausgestellt wird; `null` für einen berechtigungseingeschränkten API-Schlüssel ohne `media: read`. Fehlt, wenn kein Bild zum Eintrag gehört. front_image_url: type: string description: >- Dokumenteneinträge, die ein Bild der Dokumentenvorderseite enthalten: kurzlebige signierte URL, die bei jedem Aufruf neu ausgestellt wird; `null` für einen berechtigungseingeschränkten API-Schlüssel ohne `media: read`. full_name: type: string description: >- Aus einer Sitzung übernommene Dokumenteneinträge: vollständiger Name des Inhabers. issuing_state: type: string description: >- Aus einer Sitzung übernommene Dokumenteneinträge: Ausstellungsland nach ISO 3166-1 Alpha-3. document_type: type: string description: >- Aus einer Sitzung übernommene Dokumenteneinträge: Dokumenttyp-Code, zum Beispiel `P`, `ID` oder `DL`. region: type: string description: >- Aus einer Sitzung übernommene Dokumenteneinträge: Ausstellungs-Bundesstaat oder -Provinz eines regional ausgestellten Dokuments, leer, falls nicht zutreffend. Wird durch „Sitzungselemente zur Sperrliste hinzufügen“ nicht gesetzt. document_number: type: string description: >- Aus einer Sitzung übernommene Dokumenteneinträge: die Dokumentennummer. face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: >- Aus einem Selfie bei der Dokumentenerfassung übernommene Gesichtseinträge: welches Selfie. Fehlt bei Liveness-Gesichtern. reference_node_id: type: string nullable: true description: >- Aus einem Selfie bei der Dokumentenerfassung übernommene Gesichtseinträge: der Ausweisverifizierungs-Knoten, aus dem das Selfie stammt. fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: >- Aus einer Sitzung erfasste Geräte-Fingerprint-Einträge: wie der Fingerprint abgeleitet wurde. `persistent_id` identifiziert ein einzelnes Gerät; `composite_hash` und `legacy_fp` können von Geräten desselben Modells geteilt werden. sandbox: type: boolean description: >- `true` bei einem Gesichtseintrag, der in einer Sandbox-Anwendung hochgeladen wurde; ein solcher Eintrag stimmt mit nichts überein. reference_type: type: string enum: - transaction - vendor_user - vendor_business description: >- Von Ihnen festgelegt: Worauf `reference_object_uuid` verweist, damit die Console darauf zurückverlinkt. reference_id: type: string description: 'Von Ihnen festgelegt: Kennung des Quelldatensatzes.' created_at: type: string format: date-time description: Wann der Eintrag hinzugefügt wurde. responses: RateLimitedWrite: description: >- Das geteilte Schreiblimit von 300 Anfragen pro Minute pro API-Schlüssel wurde überschritten. Beachten Sie `Retry-After`, bevor Sie es erneut versuchen. 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: >- Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.