> ## 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.
# Aggiorna dati Document AI: API Didit
> Correggi i campi estratti da Didit da un documento Document AI o imposta il suo stato di revisione in una sessione di verifica KYC o KYB.
Prompt API per aggiornare i dati di Document AI
Copia il prompt negli appunti
\
\`Correct the extracted data of a Document AI document, or set its review status, on a Didit verification session through the API.
Endpoint:
PATCH https://verification.didit.me/v3/document-ai/{session_id}/documents/{document_uuid}/
Authentication:
Send my Didit API key in the x-api-key header. A scoped key needs decisions: write.
Goal:
\- Fix a value Document AI misread, or approve or decline a document the workflow sent to review.
Request body (JSON, both fields optional):
\- extracted_data: a JSON object of field keys to new values. Merged key by key: sent keys replace the stored values (a null value clears one), keys I leave out keep their values. Do not send extracted_data itself as null (400); leave it out instead.
\- status: "Approved", "Declined", "In Review" or "Not Finished".
Behavior:
\- Works for user (KYC) and business (KYB) session IDs.
\- {document_uuid} is document_ai_documents[].items[].uuid from GET /v3/session/{session_id}/decision/, and the document must belong to that session.
\- The document status feeds the Document AI result of its workflow node in the decision. The session status is not recomputed.
\- Every successful call, even one that changes nothing, sends a data.updated webhook with trigger "manual_review".
Example call:
curl -X PATCH "https://verification.didit.me/v3/document-ai/11111111-2222-3333-4444-555555555555/documents/44444444-5555-6666-7777-888888888888/" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"extracted_data": {"invoice_number": "INV-2026-0042"}, "status": "Approved"}'
What to read from the response:
\- extracted_data: all extracted fields after the merge.
\- status: the document's review status.
\- file_url: the storage path of the file, not a download link. Read the presigned file_url from the session decision to download it.
Failure modes:
\- 400: status is not one of the allowed values, or extracted_data is null (checked before the document is looked up).
\- 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 decisions: write, or a request from outside the key's IP allowlist.
\- 404: the session does not exist, was deleted, or is outside a scoped key's limits, or the document does not belong to the session.
Side effects: updates the document and sends a data.updated webhook.
For the full integration shape, see /integration/integration-prompt.`
\
Incolla in
Le chiavi dei campi sono quelle configurate per il documento nel workflow. Consulta [Document AI](https://docs.didit.me/it/core-technology/document-ai/overview.md) per capire come impostare documenti e campi, e il [report di Document AI](https://docs.didit.me/it/core-technology/document-ai/report-document-ai.md) per vedere dove compare il risultato nella decisione della sessione.
## OpenAPI
````yaml it/openapi-25.json PATCH /v3/document-ai/{sessionId}/documents/{documentUuid}/
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/document-ai/{sessionId}/documents/{documentUuid}/:
patch:
tags:
- Sessions
summary: Aggiorna un documento di Document AI
description: >-
Correggi i campi estratti da Document AI da un documento caricato,
imposta il suo stato di revisione, o entrambi, su una sessione KYC o
KYB. `extracted_data` deve essere un oggetto JSON e viene unito chiave
per chiave: una chiave inviata sostituisce il valore memorizzato (una
chiave inviata come `null` viene memorizzata come `null`) e le chiavi
omesse mantengono i propri valori. Lo stato del documento alimenta il
risultato Document AI del relativo nodo del workflow nella decisione
della sessione; lo stato della sessione non viene ricalcolato. Ogni
chiamata riuscita, inclusa quella che non apporta modifiche, invia un
[webhook](https://docs.didit.me/it/integration/webhooks) `data.updated`
con trigger `manual_review`. Una chiave API con restrizioni necessita di
`decisions: write`; vedi [Document
AI](https://docs.didit.me/it/core-technology/document-ai/overview).
operationId: patch_v3_document_ai_document
parameters:
- name: sessionId
in: path
required: true
description: >-
UUID della sessione di verifica (il `session_id` restituito da `POST
/v3/session/`). Accetta sia ID di sessione di Verifica degli utenti
(KYC) sia di Verifica aziendale (KYB): il server risolve l'ID per
entrambi i tipi di sessione. Deve essere un UUID ben formato; un
valore malformato non corrisponde alla route e restituisce una
pagina HTML `404`.
schema:
type: string
format: uuid
example: 11111111-2222-3333-4444-555555555555
- name: documentUuid
in: path
required: true
description: >-
UUID del documento Document AI
(`document_ai_documents[].items[].uuid` in `GET
/v3/session/{sessionId}/decision/`). Deve appartenere alla sessione
indicata nel percorso.
schema:
type: string
format: uuid
example: 44444444-5555-6666-7777-888888888888
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
extracted_data:
type: object
additionalProperties: true
description: >-
Chiavi di campo (le chiavi configurate per il documento) e i
relativi valori corretti. Deve essere un oggetto JSON; unito
chiave per chiave nei dati memorizzati. Omettilo invece di
inviare `null`, che restituisce `400`.
example:
invoice_number: INV-2026-0042
status:
type: string
enum:
- Approved
- Declined
- In Review
- Not Finished
description: Nuovo stato di revisione del documento.
example: Approved
example:
extracted_data:
invoice_number: INV-2026-0042
status: Approved
responses:
'200':
description: Documento aggiornato. Restituisce il documento dopo l'unione.
content:
application/json:
schema:
type: object
required:
- uuid
- document_key
- original_filename
- file_url
- status
- extracted_data
properties:
uuid:
type: string
format: uuid
description: Identificativo del documento.
document_key:
type: string
description: >-
Il documento configurato a cui corrisponde questo
caricamento.
original_filename:
type: string
nullable: true
description: Nome del file con cui è stato caricato il documento.
file_url:
type: string
nullable: true
description: >-
Percorso di archiviazione del file caricato. Non è un link
di download: leggi la `file_url` pre-firmata dalla
decisione della sessione per scaricare il file.
status:
type: string
enum:
- Not Finished
- Approved
- Declined
- In Review
- Resub Requested
description: Stato di revisione del documento.
extracted_data:
type: object
nullable: true
additionalProperties: true
description: >-
Tutti i campi estratti dopo l'unione, indicizzati per
chiave di campo.
example:
uuid: 44444444-5555-6666-7777-888888888888
document_key: invoice
original_filename: invoice-2026-09.pdf
file_url: >-
document_ai/11111111-2222-3333-4444-555555555555-66666666-7777-8888-9999-000000000000.pdf
status: Approved
extracted_data:
invoice_number: INV-2026-0042
total_amount: 1250
issue_date: '2026-09-01'
'400':
description: >-
Errore di validazione, verificato prima della ricerca del documento:
`status` non rientra tra i valori consentiti, oppure
`extracted_data` inviato come `null`.
content:
application/json:
examples:
Invalid status:
summary: status non è presente nell'enum
value:
status:
- '"Rejected" is not a valid choice.'
Null extracted_data:
summary: extracted_data è null
value:
extracted_data:
- This field may not be null.
'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 decisions write:
summary: 'La chiave con ambito non dispone di decisions: write'
value:
detail: This API key has no write access to decisions.
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, oppure nessun documento corrente
con questo UUID vi appartiene. 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 una chiave con ambito
limitato (restituito anche per una sessione eliminata pochi
istanti prima)
value:
detail: Session not found.
Unknown document:
summary: documentUuid non appartiene alla sessione
value:
detail: Document AI document not found.
'429':
description: >-
Limite di frequenza superato: 300 richieste di scrittura (POST,
PATCH, DELETE) al minuto per chiave API. 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: >-
Write request rate limit exceeded. You can make up to 300
requests per minute.
headers:
Retry-After:
description: Secondi da attendere prima di effettuare un nuovo tentativo.
schema:
type: integer
minimum: 1
example: 30
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X PATCH
'https://verification.didit.me/v3/document-ai/11111111-2222-3333-4444-555555555555/documents/44444444-5555-6666-7777-888888888888/'
\
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"extracted_data": {"invoice_number": "INV-2026-0042"}, "status": "Approved"}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.update_document_ai_data(
"11111111-2222-3333-4444-555555555555",
"44444444-5555-6666-7777-888888888888",
extracted_data={"invoice_number": "INV-2026-0042"},
status="Approved",
)
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.sessions.updateDocumentAiData(
"11111111-2222-3333-4444-555555555555",
"44444444-5555-6666-7777-888888888888",
{
extracted_data: { invoice_number: "INV-2026-0042" },
status: "Approved",
},
);
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateDocumentAiData(ctx, \"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", didit.SessionsUpdateDocumentAiDataParams{\n\tExtractedData: didit.Some(map[string]any{\"invoice_number\": \"INV-2026-0042\"}),\n\tStatus: didit.Some(didit.SessionsUpdateDocumentAiDataParamsStatus(\"Approved\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsUpdateDocumentAiDataParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.sessions().updateDocumentAiData("11111111-2222-3333-4444-555555555555",
"44444444-5555-6666-7777-888888888888",
SessionsUpdateDocumentAiDataParams.builder()
.extractedData(Map.of("invoice_number", "INV-2026-0042"))
.status(SessionsUpdateDocumentAiDataParams.Status.of("Approved"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
sessions->updateDocumentAiData('11111111-2222-3333-4444-555555555555',
'44444444-5555-6666-7777-888888888888', [
'extracted_data' => ['invoice_number' => 'INV-2026-0042'],
'status' => 'Approved',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.update_document_ai_data(
"11111111-2222-3333-4444-555555555555",
"44444444-5555-6666-7777-888888888888",
extracted_data: { invoice_number: "INV-2026-0042" },
status: "Approved"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await
client.Sessions.UpdateDocumentAiDataAsync("11111111-2222-3333-4444-555555555555",
"44444444-5555-6666-7777-888888888888", new
SessionsUpdateDocumentAiDataParams
{
ExtractedData = new Dictionary { ["invoice_number"] = "INV-2026-0042" },
Status = new SessionsUpdateDocumentAiDataParamsStatus("Approved"),
});
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.