> ## 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. # Gesichtsbild hochladen API: Vendor-Benutzerprofil > Lade ein Base64-Gesichtsbild in ein bestehendes Didit-Benutzerprofil hoch, nachdem der Benutzer mit vendor_data angelegt oder importiert wurde. Prompt zum Hochladen eines Benutzergesichts Prompt in die Zwischenablage kopieren \

\`Goal: Attach a trusted imported face image to an existing Didit User profile.

Use case: I am migrating users from another provider. I already have a stable vendor_data and a face image I am allowed to process. I want the User profile to carry that face for evidence, duplicate detection, and face search.

Flow:
1\. Create or retrieve the User by vendor_data:
POST https://verification.didit.me/v3/users/create/
GET  https://verification.didit.me/v3/users/{vendor_data}/
2\. Read didit_internal_id from the User response.
3\. Upload the face to:
POST https://verification.didit.me/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

Auth: x-api-key for the same application.
Content-Type: application/json

Request body:
\- image (string, required) — raw base64-encoded JPG or PNG. Do not include a data URL prefix. Max decoded size: 2 MB.
\- comment (string, optional) — operator-visible note, for example "Imported from previous KYC provider".

Response 201:
\{
"uuid": "face-upload-uuid",
"image_url": "https://signed-url.example/...",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}

Limits:
\- Max 5 manually uploaded faces per User.
\- The image must decode as an image and contain a detectable face.
\- This enrolls the face for profile evidence and matching. It does not add the face to a blocklist.

To block a face, use POST /v3/lists/{list_uuid}/entries/face-upload/ with a face-type list instead.`

\
Einfügen in ## ÜbersichtVerwenden Sie diesen Endpoint, wenn Sie Benutzer von einem anderen Anbieter importieren und bereits für jede Person ein vertrauenswürdiges Gesichtsbild haben. Der Benutzer bleibt über Ihr `vendor_data` referenziert, aber dieser Endpoint zum Anhängen von Gesichtern an ein Profil verwendet `didit_internal_id`, damit der Zielbenutzer eindeutig ist.> [!NOTE] > > Dies unterscheidet sich von [Gesicht zur Liste hochladen](https://docs.didit.me/de/management-api/lists/upload-face.md). Der Profil-Upload hängt ein Gesicht als Nachweis an einen Benutzer an und wird für Duplikaterkennung und Gesichtssuche verwendet. Der Listen-Upload fügt ein Gesicht zu einer Sperrliste mit Gesichtern hinzu, damit künftige Matching-Sitzungen abgelehnt werden können.## Endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## Migrationsablauf**1. Benutzer anlegen oder finden**Rufen Sie [`POST /v3/users/create/`](https://docs.didit.me/de/management-api/users/create) für ein neues Profil auf oder [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/de/management-api/users/get) für ein bestehendes Profil.**2. didit\_internal\_id speichern**Die Benutzerantwort enthält `didit_internal_id`. Verwenden Sie in Ihrer Datenbank weiterhin `vendor_data`; verwenden Sie `didit_internal_id` nur für Endpoints zum Anhängen von Gesichtern an ein Profil.**3. Gesicht hochladen**Senden Sie ein rohes Base64-kodiertes Bild im Feld `image`. Das Backend prüft vor dem Speichern die Bilddekodierung, die Bildgröße und die Gesichtserkennung.## Beispiel```bash theme={null} # 1. Create the User keyed by your external id curl -X POST https://verification.didit.me/v3/users/create/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "vendor_data": "user-42", "display_name": "Jane Doe", "metadata": { "previous_provider": "legacy-kyc-vendor" } }' # 2. Upload an imported face to the returned didit_internal_id curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image": "", "comment": "Imported from previous KYC provider" }' ```## Anfragetext| Feld | Typ | Pflicht | Beschreibung | | - | - | - | - | | `image` | string | Ja | Rohes Base64-kodiertes JPG- oder PNG-Bild. Fügen Sie kein `data:image/...;base64,` hinzu. Maximale dekodierte Größe: 2 MB. | | `comment` | string | Nein | Für Bediener sichtbare Notiz, die im Benutzerprofil angezeigt wird. |## Antwort```json theme={null} { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "image_url": "https://signed-url.example/face.jpg", "comment": "Imported from previous KYC provider", "uploaded_by": "api", "created_at": "2026-05-18T12:00:00Z" } ```## Validierung und Limits- Maximal 5 manuell hochgeladene Gesichter pro Benutzer. - Die maximale dekodierte Bildgröße beträgt 2 MB. - Das Bild muss gültiges Base64 sein und sich als Bild dekodieren lassen. - Das Bild muss ein erkennbares Gesicht enthalten. Verwenden Sie nach Möglichkeit einen frontalen, gut ausgeleuchteten Gesichtsausschnitt. - Das hochgeladene Gesicht wird für künftige Duplikaterkennung und Gesichtssuche indexiert. - Das hochgeladene Gesicht wird nicht automatisch auf die Sperrliste gesetzt.## Profilgesichter auflisten oder löschenProfilgesichter auflisten:```bash theme={null} curl https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/ \ -H "x-api-key: YOUR_API_KEY" ```Ein Profilgesicht löschen:```bash theme={null} curl -X DELETE https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/$FACE_UUID/ \ -H "x-api-key: YOUR_API_KEY" ```## BerechtigungenVerwenden Sie einen API-Schlüssel derselben Anwendung. Der Schlüssel muss zu einer App gehören, die das Zielprofil des Benutzers verwalten darf.## Fehlerszenarien- `400`: ungültiges Base64, ungültiges Bild, kein erkennbares Gesicht, Bild größer als 2 MB oder der Benutzer hat bereits 5 hochgeladene Gesichter. - `401`: fehlende oder ungültige Zugangsdaten. - `403`: Der API-Schlüssel ist gültig, darf dieses Benutzerprofil aber nicht verwalten. - `404`: In der Anwendung existiert kein Benutzer für diese `didit_internal_id`. - `429`: Rate-Limit erreicht; warten Sie gemäß `Retry-After`, bevor Sie es erneut versuchen.## Verwandte Seiten- [Benutzer erstellen](https://docs.didit.me/de/management-api/users/create.md) - [Benutzer abrufen](https://docs.didit.me/de/management-api/users/get.md) - [Benutzer importieren und exportieren](https://docs.didit.me/de/entities/users/import-export.md) - [Gesichter und Biometrie](https://docs.didit.me/de/entities/users/faces-and-biometrics.md) - [Gesicht zur Sperrliste hochladen](https://docs.didit.me/de/management-api/lists/upload-face.md) ## OpenAPI ````yaml de/openapi-25.json POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/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/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/: post: tags: - Users summary: Benutzergesicht hochladen description: >- Ein vertrauenswürdiges, importiertes Gesichtsbild an ein bestehendes Benutzerprofil anhängen. Verwenden Sie dies, nachdem Sie einen Benutzer über `vendor_data` erstellt oder abgerufen und dessen `didit_internal_id` ausgelesen haben. Das hochgeladene Gesicht wird im Benutzerprofil gespeichert und für die Duplikaterkennung sowie Gesichtssuche indexiert. Es wird nicht zu einer Gesichts-Sperrliste hinzugefügt. operationId: upload_user_face parameters: - name: organization_id in: path required: true schema: type: string format: uuid description: UUID der Organisation, der die Anwendung gehört. - name: application_id in: path required: true schema: type: string format: uuid description: UUID der Anwendung, zu der das Benutzerprofil gehört. - name: didit_internal_id in: path required: true schema: type: string format: uuid description: >- Didits interne Benutzer-UUID, zurückgegeben als `didit_internal_id` von `GET /v3/users/{vendor_data}/` und `POST /v3/users/create/`. requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- Unverarbeitetes Base64-codiertes JPG- oder PNG-Gesichtsbild. Kein `data:image/...;base64,`-Präfix angeben. Maximale decodierte Größe: 2 MB. comment: type: string description: >- Optionale, für den Bearbeiter sichtbare Notiz zum hochgeladenen Gesicht. default: '' examples: Imported face: summary: >- Ein von einem vorherigen Anbieter importiertes Gesicht anhängen value: image: /9j/4AAQSkZJRgABAQEA... comment: Imported from previous KYC provider responses: '201': description: Gesicht hochgeladen und dem Benutzerprofil zugeordnet. content: application/json: schema: type: object required: - uuid - image_url - comment - uploaded_by - created_at properties: uuid: type: string format: uuid description: UUID des hochgeladenen Benutzer-Gesichtsdatensatzes. image_url: type: string format: uri nullable: true description: Signierte URL für das hochgeladene Gesichtsbild. comment: type: string nullable: true description: >- Kommentar, der beim Hochladen des Gesichts angegeben wurde. uploaded_by: type: string nullable: true description: >- E-Mail oder Akteurskennung des Uploaders, sofern verfügbar. created_at: type: string format: date-time description: Zeitstempel des Uploads. examples: Uploaded: value: uuid: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee image_url: https://signed-url.example/face.jpg comment: Imported from previous KYC provider uploaded_by: api created_at: '2026-05-18T12:00:00Z' '400': description: >- Ungültiger Anfrage-Body oder ungültiges Bild. Häufige Ursachen: ungültiges Base64, ungültiges Bild, kein erkennbares Gesicht, Bild über 2 MB, fehlendes Embedding oder der Benutzer hat bereits 5 hochgeladene Gesichter. content: application/json: examples: No face: value: image: >- No face detected in the image. Please upload a clear photo with a visible face. Too many faces: value: detail: Maximum of 5 faces per user reached. Too large: value: image: Image exceeds maximum size of 2 MB. '401': description: Fehlender oder ungültiger API-Schlüssel. content: application/json: examples: Missing key: value: detail: Authentication credentials were not provided. '403': description: >- Der Berechtigungsnachweis ist gültig, kann jedoch keine Benutzerprofile für diese Anwendung schreiben. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: >- Für diese `didit_internal_id` existiert kein Benutzer in der Anwendung. content: application/json: examples: Not found: value: detail: Not found. '429': description: >- Rate-Limit überschritten; drosseln Sie die Anfragen und wiederholen Sie den Versuch. content: application/json: examples: Rate limited: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider"}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID # and DIDIT_APPLICATION_ID. client = Didit() result = client.users.upload_face( "11111111-2222-3333-4444-555555555555", image="/9j/4AAQSkZJRgABAQEA...", comment="Imported from previous KYC provider", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID // and DIDIT_APPLICATION_ID. const didit = new Didit(); const result = await didit.users.uploadFace("11111111-2222-3333-4444-555555555555", { image: "/9j/4AAQSkZJRgABAQEA...", comment: "Imported from previous KYC provider", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\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.UsersUploadFaceParams; // Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID // and DIDIT_APPLICATION_ID. Didit client = new Didit(); var result = client.users().uploadFace("11111111-2222-3333-4444-555555555555", UsersUploadFaceParams.builder() .image("/9j/4AAQSkZJRgABAQEA...") .comment("Imported from previous KYC provider") .build()); System.out.println(result); - lang: php label: PHP source: >- users->uploadFace('11111111-2222-3333-4444-555555555555', [ 'image' => '/9j/4AAQSkZJRgABAQEA...', 'comment' => 'Imported from previous KYC provider', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID # and DIDIT_APPLICATION_ID. didit = Didit::Client.new result = didit.users.upload_face( "11111111-2222-3333-4444-555555555555", image: "/9j/4AAQSkZJRgABAQEA...", comment: "Imported from previous KYC provider" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID // and DIDIT_APPLICATION_ID. using var client = new DiditClient(); var result = await client.Users.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new UsersUploadFaceParams { Image = "/9j/4AAQSkZJRgABAQEA...", Comment = "Imported from previous KYC provider", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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.