Vai al contenuto principale
POST
curl

Panoramica

Usa 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.
Questo è diverso da Carica volto nella lista. 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/ per un nuovo profilo, oppure GET /v3/users/{vendor_data}/ 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

Corpo della richiesta

Risposta

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 caricati

Elenca i volti del profilo:
Elimina un volto del profilo:

Autorizzazioni

Usa 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

Autorizzazioni

x-api-key
string
header
obbligatorio

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.

Parametri del percorso

organization_id
string<uuid>
obbligatorio

UUID dell'organizzazione proprietaria dell'applicazione.

application_id
string<uuid>
obbligatorio

UUID dell'applicazione a cui appartiene il profilo utente.

didit_internal_id
string<uuid>
obbligatorio

UUID utente interno di Didit, restituito come didit_internal_id da GET /v3/users/{vendor_data}/ e POST /v3/users/create/.

Corpo

application/json
image
string<byte>
obbligatorio

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
string
predefinito:""

Nota opzionale visibile all'operatore per il volto caricato.

Risposta

Volto caricato e collegato al profilo utente.

uuid
string<uuid>
obbligatorio

UUID del record del volto dell'utente caricato.

image_url
string<uri> | null
obbligatorio

URL firmato per l'immagine del volto caricata.

comment
string | null
obbligatorio

Commento fornito al momento del caricamento del volto.

uploaded_by
string | null
obbligatorio

Email o identificatore del soggetto che ha effettuato il caricamento, se disponibile.

created_at
string<date-time>
obbligatorio

Timestamp del caricamento.

Ultima modifica il 7 novembre 2026