> ## 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.
# Aggiungi immagini a una sessione API
> Con Didit, allega un'immagine o un PDF extra alla verifica dell'identità o alla prova di residenza di una sessione KYC conclusa.
Aggiungi immagini a una sessione: prompt per API
Copia il prompt negli appunti
\`Attach an extra image or PDF to a finished Didit User Verification (KYC) session through the API.
Endpoint:
PATCH [https://verification.didit.me/v3/session/\{session\_id}/add-images/](https://verification.didit.me/v3/session/\{session_id}/add-images/)
Authentication:
Send my Didit API key in the x-api-key header. A scoped key needs sessions: write.
Goal:
* Add evidence collected outside the verification flow (for example the back of an ID document, or a supporting letter) to the session's ID verification or Proof of Address result, so reviewers see it with the rest of the session.
Request (multipart/form-data):
* file (required): JPG, JPEG, PNG, WEBP, TIFF or PDF, at most 15 MB as uploaded. Didit compresses it and rejects it if it is still over 2 MB (2,097,152 bytes) after compression.
* model\_type (required): "kyc" for the ID verification, "poa" for the Proof of Address.
* file\_password (optional): the password of an encrypted PDF.
Behavior:
* The session must be Approved, Declined, In Review or Kyc Expired, and must have the result named by model\_type. Business (KYB) sessions are not supported.
* When the step ran more than once, the file goes to the most recent result.
* Each call adds one file and keeps the existing ones.
* The file then appears in extra\_files of id\_verifications\[] or poa\_verifications\[] in GET /v3/session/{session_id}/decision/.
* A FILE\_ADDED entry is added to the session's activity log. No webhook is sent and the session status does not change.
* Rate limit: 10 requests per minute per API key.
Example call:
curl -X PATCH "[https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/](https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/)" \
-H "x-api-key: YOUR\_API\_KEY" \
-F "file=@back-of-id.jpg" \
-F "model\_type=kyc"
What to read from the response:
* extra\_files: short-lived presigned links to every extra file of that result, including the new one. A scoped key without media: read receives them as null.
Failure modes:
* 400: file or model\_type missing, unsupported format, file too large before or after compression, encrypted PDF without the right file\_password.
* 401: the API key has expired.
* 403: missing key (a wrong, revoked or expired key gets 401), a key of another application, a scoped key without sessions: write, or a request from outside the key's IP allowlist.
* 404: the session does not exist, was deleted, is outside a scoped key's limits, is not in a reviewable status, or has no result of that model\_type.
* 429: more than 10 calls in a minute. Wait for Retry-After seconds.
Side effects: stores the file with the session and adds an activity entry.
For the full integration shape, see /integration/integration-prompt.\`
Incolla in
I link pre-firmati in `extra_files` scadono. Leggi quelli nuovi dalla [decisione della sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md) quando ti servono di nuovo i file. Per correggere i dati estratti da un documento, usa invece [Aggiorna i dati della sessione](https://docs.didit.me/it/sessions-api/update-data.md).
## OpenAPI
````yaml it/openapi-25.json PATCH /v3/session/{sessionId}/add-images/
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/session/{sessionId}/add-images/:
patch:
tags:
- Sessions
summary: Aggiungi un'immagine a una sessione
description: >-
Allega un'immagine o un PDF aggiuntivo al risultato della verifica
dell'identità (`model_type=kyc`) o della Prova di residenza
(`model_type=poa`) di una sessione di Verifica degli utenti (KYC)
conclusa, ad esempio prove raccolte al di fuori del workflow. La
sessione deve essere `Approved`, `Declined`, `In Review` o `Kyc Expired`
e includere il risultato indicato da `model_type`; le sessioni di
Verifica aziendale (KYB) non sono supportate. Ogni chiamata aggiunge un
file (al risultato più recente quando il passaggio è stato eseguito più
di una volta), mantiene i file esistenti e registra una voce
`FILE_ADDED` nel registro di attività della sessione; il caricamento non
invia webhook e non modifica lo stato della sessione. Il file viene
compresso durante il caricamento e viene restituito in `extra_files`
della decisione della sessione. Questo endpoint è limitato a 10
richieste al minuto per chiave API. Una chiave API con ambito limitato
richiede `sessions: write`, e senza `media: read` riceve i link di
`extra_files` come `null`.
operationId: patch_v3_session_add_images
parameters:
- name: sessionId
in: path
required: true
description: >-
UUID della sessione di Verifica degli utenti (KYC) a cui aggiungere
il file (il `session_id` restituito da `POST /v3/session/`). L'ID di
una sessione di Verifica aziendale (KYB) restituisce `404`.
schema:
type: string
format: uuid
example: 11111111-2222-3333-4444-555555555555
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- model_type
properties:
file:
type: string
format: binary
description: >-
L'immagine o il PDF. Estensioni consentite: `jpg`, `jpeg`,
`png`, `webp`, `tiff`, `pdf`. Al massimo 15 MB al
caricamento; il file viene poi compresso e rifiutato con
`400` se supera ancora i 2 MB (2.097.152 byte). I file vuoti
vengono rifiutati.
model_type:
type: string
enum:
- kyc
- poa
description: >-
`kyc` aggiunge il file al risultato della verifica
dell'identità, `poa` al risultato della prova di residenza.
example: kyc
file_password:
type: string
description: >-
Password di un PDF crittografato. Senza di essa, o con una
password errata, un PDF crittografato restituisce `400`.
example:
file: (binary)
model_type: kyc
responses:
'200':
description: >-
File aggiunto. Restituisce tutti i file aggiuntivi di quel
risultato, compreso quello nuovo.
content:
application/json:
schema:
type: object
required:
- extra_files
properties:
extra_files:
type: array
description: >-
Link pre-firmati di breve durata a tutti i file extra del
risultato indicato da `model_type`, dal più vecchio al più
recente. Ciascun link è `null` per una chiave API con
ambito limitato senza `media: read`. Leggi nuovi link in
seguito dalla decisione della sessione.
items:
type: string
format: uri
nullable: true
example:
extra_files:
- >-
https://media.example.com/session/11111111-2222-3333-4444-555555555555/kyc-extra-files/66666666-7777-8888-9999-000000000000.jpg?expires=1789383731&signature=abc123
'400':
description: >-
Errore di validazione. Gli errori di campo arrivano come
`{"": [""]}`; gli errori per PDF crittografato come
`{"detail": "..."}`.
content:
application/json:
examples:
Missing file:
summary: Nessuna parte di file nel modulo
value:
file:
- No file was submitted.
Missing model_type:
summary: model_type omesso
value:
model_type:
- This field is required.
Invalid model_type:
summary: model_type non è kyc o poa
value:
model_type:
- '"passport" is not a valid choice.'
File too large:
summary: Caricamento superiore a 15 MB
value:
file:
- File size should not exceed 15 MB
Too large after compression:
summary: Ancora superiore a 2 MB dopo la compressione
value:
file:
- File size is too big. Max allowed size is 2097152 bytes.
Encrypted PDF:
summary: PDF crittografato senza file_password
value:
detail: >-
The PDF is encrypted. Please upload a decrypted PDF or a
photo instead.
Wrong PDF password:
summary: file_password non apre il PDF
value:
detail: >-
The PDF password is incorrect. Please provide the correct
password.
'401':
description: >-
La chiave API con ambito è scaduta. Questo è l'unico caso che
restituisce `401`: una chiave mancante, non valida o revocata
restituisce `403`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Messaggio di errore di facile lettura.
examples:
Expired key:
summary: La data di scadenza della chiave è stata superata
value:
detail: This API key has expired.
'403':
description: >-
Errore di autenticazione o autorizzazione. Una chiave mancante
restituisce `403`, così come la chiave di un'altra applicazione, una
chiave con ambito limitato priva dell'autorizzazione necessaria per
questo endpoint e una richiesta proveniente dall'esterno
dell'allowlist IP della chiave; una chiave errata, revocata o
scaduta restituisce `401`. Distinguili tramite `detail`.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Messaggio di errore di facile lettura.
examples:
Missing or invalid credentials:
summary: >-
Nessuna intestazione x-api-key, oppure validazione della
chiave non riuscita
value:
detail: >-
Authentication credentials were not provided or are
invalid.
Other application:
summary: >-
Una chiave valida appartenente a un'applicazione diversa da
quella della sessione
value:
detail: You do not have permission to perform this action.
Scoped key without sessions write:
summary: 'La chiave con ambito non dispone di sessions: write'
value:
detail: This API key has no write access to sessions.
IP not allowed:
summary: >-
Richiesta proveniente da un indirizzo esterno all'allowlist
degli IP della chiave
value:
detail: This API key can't be used from this IP address.
'404':
description: >-
La sessione non esiste, è stata eliminata o non rientra nei limiti
di una chiave con ambito limitato; è una sessione KYB o non è in
stato `Approved`, `Declined`, `In Review` o `Kyc Expired`; oppure
non ha alcun risultato per il `model_type` richiesto (verificato
prima della convalida del file). La ricerca della sessione viene
eseguita prima della verifica delle credenziali, quindi un
`sessionId` sconosciuto restituisce `404` anche senza una chiave
valida.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Messaggio di errore di facile lettura.
examples:
Unknown session:
summary: >-
Nessuna sessione con questo ID esiste, oppure è stata
eliminata
value:
detail: Not found.
Outside key limits:
summary: >-
La sessione non rientra nei limiti di workflow o di sola
approvazione di una chiave con ambito limitato
value:
detail: Session not found.
Not eligible:
summary: Sessione non ancora terminata, oppure un ID di sessione KYB
value:
detail: No Session matches the given query.
No ID verification:
summary: model_type=kyc su una sessione senza verifica dell'identità
value:
detail: The session does not have KYC data.
No Proof of Address:
summary: model_type=poa su una sessione senza prova di residenza
value:
detail: The session does not have POA data.
'429':
description: >-
Limite di frequenza superato: 10 richieste di aggiunta di immagini
al minuto per chiave API (vengono conteggiate anche le richieste
respinte). Si applica inoltre il budget condiviso di 300 richieste
di scrittura al minuto. Attendi i secondi indicati in `Retry-After`
prima di riprovare; le intestazioni `X-RateLimit-*` indicano il
budget.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Messaggio di errore di facile lettura.
examples:
Rate limited:
summary: Budget per il minuto corrente esaurito
value:
detail: >-
Session add-images rate limit exceeded. You can make up to
10 requests per minute.
headers:
Retry-After:
description: Secondi da attendere prima di effettuare un nuovo tentativo.
schema:
type: integer
minimum: 1
example: 30
'503':
$ref: '#/components/responses/DocumentProcessingBusy'
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X PATCH
'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/'
\
-H 'x-api-key: YOUR_API_KEY' \
-F 'file=@./back-of-id.jpg' \
-F 'model_type=kyc'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.add_images(
"11111111-2222-3333-4444-555555555555",
file=open("image.jpg", "rb"),
model_type="kyc",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit, { fileFromPath } from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await
didit.sessions.addImages("11111111-2222-3333-4444-555555555555", {
file: await fileFromPath("image.jpg"),
model_type: "kyc",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.AddImages(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsAddImagesParams{\n\tFile: didit.FileFromPath(\"image.jpg\"),\n\tModelType: \"kyc\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.nio.file.Path;
import me.didit.Didit;
import me.didit.types.SessionsAddImagesParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.sessions().addImages("11111111-2222-3333-4444-555555555555",
SessionsAddImagesParams.builder()
.file(Path.of("image.jpg"))
.modelType(SessionsAddImagesParams.ModelType.of("kyc"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
sessions->addImages('11111111-2222-3333-4444-555555555555',
[
'file' => File::fromPath('image.jpg'),
'model_type' => 'kyc',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.add_images(
"11111111-2222-3333-4444-555555555555",
file: Pathname("image.jpg"),
model_type: "kyc"
)
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.Sessions.AddImagesAsync("11111111-2222-3333-4444-555555555555",
new SessionsAddImagesParams
{
File = FileUpload.FromPath("image.jpg"),
ModelType = "kyc",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
responses:
DocumentProcessingBusy:
description: >-
Al momento sono in fase di elaborazione troppi documenti, pertanto
questo caricamento non è stato elaborato: non è stato memorizzato nulla
e non è stato utilizzato alcun tentativo. Invia nuovamente lo stesso
file dopo il numero di secondi indicato in `Retry-After`. Basa la logica
su `code`, non sul testo del messaggio.
headers:
Retry-After:
description: >-
Secondi da attendere prima di inviare nuovamente la stessa
richiesta.
schema:
type: integer
example: 10
content:
application/json:
schema:
type: object
required:
- detail
- code
properties:
detail:
type: string
code:
type: string
enum:
- document_processing_busy
example:
detail: We are busy processing documents. Please try again in a moment.
code: document_processing_busy
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.