> ## 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 caricamento volto utente: profilo utente fornitore > Carica un'immagine del volto in base64 su un profilo utente Didit esistente, dopo aver creato o importato l'utente con vendor_data. Prompt per il caricamento del volto dell'utente Copia il prompt negli appunti \

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

\
Incolla in ## PanoramicaUsa questo endpoint quando importi utenti da un altro provider e disponi già di un'immagine del volto affidabile per ogni persona. L'utente resta identificato dal tuo `vendor_data`, ma questo endpoint di allegato del profilo usa `didit_internal_id` per individuare in modo univoco l'utente di destinazione.> [!NOTE] > > Questo è diverso da [Carica volto nella lista](https://docs.didit.me/it/management-api/lists/upload-face.md). Il caricamento nel profilo allega un volto a un utente per le prove, il rilevamento dei duplicati e la ricerca facciale. Il caricamento in lista aggiunge un volto a una blocklist di tipo volto, così le future sessioni di confronto possono essere rifiutate.## Endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## Flusso di migrazione**1. Crea o trova l'utente**Chiama [`POST /v3/users/create/`](https://docs.didit.me/it/management-api/users/create) per un nuovo profilo, oppure [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/it/management-api/users/get) per uno esistente.**2. Salva didit\_internal\_id**La risposta dell'utente include `didit_internal_id`. Continua a usare `vendor_data` nel tuo database; usa `didit_internal_id` solo per gli endpoint di allegato del profilo.**3. Carica il volto**Invia un'immagine base64 grezza nel campo `image`. Il backend verifica la decodifica dell'immagine, le dimensioni dell'immagine e il rilevamento del volto prima di salvarla.## Esempio```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" }' ```## Corpo della richiesta| Campo | Tipo | Obbligatorio | Descrizione | | - | - | - | - | | `image` | string | Sì | JPG o PNG codificato in base64 grezzo. Non includere `data:image/...;base64,`. Dimensione massima decodificata: 2 MB. | | `comment` | string | No | Nota visibile agli operatori, mostrata nel profilo dell'utente. |## Risposta```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" } ```## Validazione e limiti- Massimo 5 volti caricati manualmente per ogni utente. - La dimensione massima dell'immagine decodificata è di 2 MB. - L'immagine deve essere in base64 valido e poter essere decodificata come immagine. - L'immagine deve contenere un volto rilevabile. Quando possibile, usa un ritaglio frontale di un volto ben illuminato. - Il volto caricato viene indicizzato per il futuro rilevamento dei duplicati e per la ricerca facciale. - Il volto caricato non viene inserito automaticamente in blocklist.## Elencare o eliminare i volti caricatiElenca i volti del profilo:```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" ```Elimina un volto del profilo:```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" ```## AutorizzazioniUsa una chiave API della stessa applicazione. La chiave deve appartenere a un'app autorizzata a gestire il profilo dell'utente di destinazione.## Casi di errore- `400`: base64 non valido, immagine non valida, nessun volto rilevabile, immagine superiore a 2 MB, oppure l'utente ha già 5 volti caricati. - `401`: credenziali mancanti o non valide. - `403`: la chiave API è valida ma non è autorizzata a gestire il profilo di questo utente. - `404`: non esiste alcun utente con quel `didit_internal_id` nell'applicazione. - `429`: limite di frequenza superato; attendi e riprova usando `Retry-After`.## Argomenti correlati- [Crea utente](https://docs.didit.me/it/management-api/users/create.md) - [Recupera utente](https://docs.didit.me/it/management-api/users/get.md) - [Importa ed esporta utenti](https://docs.didit.me/it/entities/users/import-export.md) - [Volti e dati biometrici](https://docs.didit.me/it/entities/users/faces-and-biometrics.md) - [Carica volto nella blocklist](https://docs.didit.me/it/management-api/lists/upload-face.md) ## OpenAPI ````yaml it/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 di verifica dell'identità. Autenticati con l'intestazione x-api-key. 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: Carica il volto dell'utente description: >- Collega un'immagine del volto importata e affidabile a un profilo Utente esistente. Usa questo endpoint dopo aver creato o recuperato un Utente tramite `vendor_data` e aver letto il suo `didit_internal_id`. Il volto caricato viene memorizzato nel profilo Utente e indicizzato per il rilevamento dei duplicati e la ricerca facciale. Non viene aggiunto a una blocklist facciale. operationId: upload_user_face parameters: - name: organization_id in: path required: true schema: type: string format: uuid description: UUID dell'organizzazione proprietaria dell'applicazione. - name: application_id in: path required: true schema: type: string format: uuid description: UUID dell'applicazione a cui appartiene il profilo utente. - name: didit_internal_id in: path required: true schema: type: string format: uuid description: >- UUID utente interno di Didit, restituito come `didit_internal_id` da `GET /v3/users/{vendor_data}/` e `POST /v3/users/create/`. requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- Immagine del volto in formato JPG o PNG non elaborata con codifica base64. Non includere il prefisso `data:image/...;base64,`. Dimensione massima decodificata: 2 MB. comment: type: string description: Nota opzionale visibile all'operatore per il volto caricato. default: '' examples: Imported face: summary: Collega un volto importato da un provider precedente value: image: /9j/4AAQSkZJRgABAQEA... comment: Imported from previous KYC provider responses: '201': description: Volto caricato e collegato al profilo utente. content: application/json: schema: type: object required: - uuid - image_url - comment - uploaded_by - created_at properties: uuid: type: string format: uuid description: UUID del record del volto dell'utente caricato. image_url: type: string format: uri nullable: true description: URL firmato per l'immagine del volto caricata. comment: type: string nullable: true description: Commento fornito al momento del caricamento del volto. uploaded_by: type: string nullable: true description: >- Email o identificatore del soggetto che ha effettuato il caricamento, se disponibile. created_at: type: string format: date-time description: Timestamp del caricamento. 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: >- Corpo della richiesta o immagine non validi. Cause frequenti: base64 non valido, immagine non valida, nessun volto rilevabile, immagine superiore a 2 MB, embedding mancante o l'utente ha già caricato 5 volti. 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: Chiave API mancante o non valida. content: application/json: examples: Missing key: value: detail: Authentication credentials were not provided. '403': description: >- La credenziale è valida ma non dispone dei permessi di scrittura dei profili User per questa applicazione. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: Nessun utente esiste per tale `didit_internal_id` nell'applicazione. content: application/json: examples: Not found: value: detail: Not found. '429': description: Limite di frequenza superato; rallenta e riprova. 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: >- La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.