> ## 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. # Crea nota transazione API > Con Didit, via API, aggiungi una nota in testo semplice, con menzioni facoltative di membri, alla timeline di revisione di una transazione monitorata. Prompt API per creare una nota di transazione Copia il prompt negli appunti \

\`Add a note to a Didit monitored transaction through the Management API.

Endpoint:
POST https://verification.didit.me/v3/transactions/{transaction_id}/notes/

Authentication:
Use the x-api-key header with my Didit API key. A scoped key needs transactions: write. Keys limited to specific workflows or to approved sessions cannot call this endpoint.

Goal:
\- Record context from my own systems (a support call, a manual check, an outcome from my case tool) on the transaction's review timeline, where Console reviewers see it.

Path parameter:
\- transaction_id: the Didit transaction uuid, not my own txn_id.

Request body (application/json):
\{
"note": "Customer confirmed the withdrawal by phone.",
"mentioned_emails": ["analyst@example.com"]
}
\- note: required. Plain text, no length limit. Leading and trailing whitespace is trimmed and a blank note is rejected.
\- mentioned_emails: optional list of emails of members of my organization to mention.

Behavior:
\- Returns 201 with the created note. actor_email and actor_name are null because the note comes from an API key, not a person.
\- Every mentioned email must belong to a member of my organization; one unknown address fails the whole request with 400. Mentions are stored lower-cased and de-duplicated in metadata.mentioned_emails. This endpoint does not notify the mentioned members.
\- Each call creates a new note. Retrying a request that timed out can add the same note twice, so check GET /v3/transactions/{transaction_id}/notes/ before retrying.
\- There is no API endpoint to edit or remove a note.

Example call:
curl -X POST "https://verification.didit.me/v3/transactions/{transaction_id}/notes/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": ["analyst@example.com"]}'

What to read from the response:
\- uuid: the note id.
\- created_at: when the note was stored.
\- metadata.mentioned_emails: the normalized mention list (empty when nobody was mentioned).

Failure modes:
\- 400: note missing ({"note": ["This field is required."]}) or blank, an invalid email in mentioned_emails, or a mentioned address outside my organization ({"mentioned_emails": ["Mentioned users must belong to this organization and have access to this application."]}).
\- 401: the API key has expired.
\- 403: missing API key (a wrong, revoked or expired key gets 401), a scoped key without transactions: write ({"detail": "This API key has no write access to transactions."}), a key with workflow or status limits, or a request from outside the key's IP allowlist.
\- 404: no transaction with this uuid in my application ({"detail": "No Transaction matches the given query."}).
\- 429: more than 300 write requests per minute with this key; wait Retry-After seconds and retry.

Side effects: creates the note and adds a TRANSACTION_NOTE_ADDED entry to the transaction's activities. The transaction's status, score and alerts do not change, no webhook is sent, and nothing is billed.

For the full integration shape, see /integration/integration-prompt.`

\
Incolla in Una nota fornisce contesto, non è una decisione: non modifica mai lo `status`, lo `score` né gli alert della transazione. I revisori la vedono nella sezione **Note** del [dettaglio della transazione](https://docs.didit.me/it/transaction-monitoring/console.md#dettaglio-della-transazione) nella Console, e le `activities` della transazione si arricchiscono di una voce `TRANSACTION_NOTE_ADDED`, che puoi leggere con [Ottieni transazione](https://docs.didit.me/it/management-api/transactions/get.md).Poiché la nota proviene da una chiave API, non ha un autore: `actor_email` e `actor_name` sono `null`. Se devi mostrare chi l'ha scritta, includi questa informazione nel testo della nota. Leggi la cronologia completa con [Elenca le note della transazione](https://docs.didit.me/it/management-api/transactions/list-notes.md). ## OpenAPI ````yaml it/openapi-25.json POST /v3/transactions/{transaction_id}/notes/ 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/transactions/{transaction_id}/notes/: post: tags: - Transactions summary: Crea nota della transazione description: >- Aggiungi una nota in testo normale alla cronologia di revisione di una transazione monitorata, visibile ai revisori nella Console. Una nota fornisce contesto, non è una decisione: i valori `status`, `score` e gli alert della transazione non cambiano, non viene inviato alcun webhook e non viene addebitato nulla. Le `activities` della transazione ricevono una voce `TRANSACTION_NOTE_ADDED`. Le note create con una chiave API non hanno un autore: `actor_email` e `actor_name` sono `null`, quindi inserisci l'autore nel testo se necessario. Ogni indirizzo in `mentioned_emails` deve appartenere a un membro della tua organizzazione, altrimenti l'intera richiesta fallisce con `400`; le menzioni vengono salvate in minuscolo e deduplicate, e questo endpoint non invia notifiche ai membri menzionati. Ogni chiamata crea una nuova nota, quindi ripetere una richiesta andata in timeout può aggiungerla due volte: elenca le note prima di riprovare. Non esiste un endpoint API per modificare o rimuovere una nota. Una chiave API con ambito limitato richiede `transactions: write`; una chiave limitata a determinati workflow o a sessioni approvate non può chiamare questo endpoint. operationId: create_transaction_note parameters: - name: transaction_id in: path required: true description: >- UUID della transazione Didit: l'`uuid` restituito da `POST /v3/transactions/` e `GET /v3/transactions/`. Il tuo `txn_id` personale non è accettato. schema: type: string format: uuid example: abcdef12-3456-7890-abcd-ef1234567890 requestBody: required: true content: application/json: schema: type: object required: - note properties: note: type: string minLength: 1 description: >- Nota in testo normale. Gli spazi vuoti iniziali e finali vengono rimossi e una nota vuota viene rifiutata. Nessun limite di lunghezza. mentioned_emails: type: array items: type: string format: email default: [] description: >- Indirizzi email dei membri della tua organizzazione da menzionare. Ognuno deve essere un'email valida di un membro dell'organizzazione. examples: Note with a mention: value: note: Customer confirmed the withdrawal by phone. mentioned_emails: - analyst@example.com Plain note: value: note: Source of funds document requested by email. responses: '201': description: La nota è stata creata. content: application/json: schema: $ref: '#/components/schemas/TransactionNote' examples: Created: value: uuid: c1111111-2222-4333-8444-555555555555 note: Customer confirmed the withdrawal by phone. actor_email: null actor_name: null metadata: mentioned_emails: - analyst@example.com created_at: '2026-10-16T10:05:12.481203Z' '400': description: >- Il corpo non è valido: `note` mancante, null o vuoto, un indirizzo non valido in `mentioned_emails` (errori indicizzati in base alla posizione nella lista) o un indirizzo menzionato che non è membro della tua organizzazione. Non è stato creato nulla. content: application/json: schema: type: object description: Errori di campo indicizzati per nome campo. additionalProperties: {} examples: Missing note: value: note: - This field is required. Blank note: value: note: - This field may not be blank. Invalid email: value: mentioned_emails: '0': - Enter a valid email address. Not an organization member: value: mentioned_emails: - >- Mentioned users must belong to this organization and have access to this application. '401': description: >- La chiave API è scaduta. Solo una chiave creata con una data di scadenza può scadere; dopo tale data ogni richiesta inviata con essa risponde con `401`. content: application/json: schema: type: object properties: detail: type: string examples: Expired key: value: detail: This API key has expired. '403': description: >- La richiesta non è consentita. Una chiave mancante riceve il messaggio generico; una chiave errata, revocata o scaduta riceve `401`. content: application/json: schema: type: object properties: detail: type: string examples: Missing or invalid key: value: detail: You do not have permission to perform this action. Scoped key without transactions write: value: detail: This API key has no write access to transactions. Key limited to workflows or approved sessions: value: detail: >- This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint. Outside the key's IP list: value: detail: This API key can't be used from this IP address. '404': description: >- Nessuna transazione con questo UUID esiste nell'applicazione (mai creata, eliminata o di proprietà di un'altra applicazione). Un `transaction_id` che non è un UUID non raggiunge l'API: restituisce una pagina HTML `404` invece di questo corpo JSON. content: application/json: schema: type: object properties: detail: type: string examples: Not found: value: detail: No Transaction matches the given query. '429': description: >- Più di 300 richieste di scrittura al minuto con questa chiave API. Attendi il numero di secondi indicato in `Retry-After`, quindi riprova. content: application/json: schema: type: object properties: detail: type: string examples: Throttled: value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. headers: Retry-After: description: >- Secondi fino al ripristino della finestra temporale corrente di un minuto. schema: type: integer example: 23 X-RateLimit-Limit: description: Richieste consentite al minuto per questo budget. schema: type: integer X-RateLimit-Remaining: description: Richieste rimanenti nell'intervallo corrente. schema: type: integer X-RateLimit-Reset: description: Ora Unix in cui la finestra si azzera. schema: type: integer security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": ["analyst@example.com"]}' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.transactions.notes.create( "abcdef12-3456-7890-abcd-ef1234567890", note="Customer confirmed the withdrawal by phone.", mentioned_emails=["analyst@example.com"], ) 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.transactions.notes.create("abcdef12-3456-7890-abcd-ef1234567890", { note: "Customer confirmed the withdrawal by phone.", mentioned_emails: ["analyst@example.com"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Notes.Create(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesCreateParams{\n\tNote: \"Customer confirmed the withdrawal by phone.\",\n\tMentionedEmails: didit.Some([]string{\"analyst@example.com\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.TransactionsNotesCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.transactions().notes().create("abcdef12-3456-7890-abcd-ef1234567890", TransactionsNotesCreateParams.builder() .note("Customer confirmed the withdrawal by phone.") .mentionedEmails(List.of("analyst@example.com")) .build()); System.out.println(result); - lang: php label: PHP source: >- transactions->notes->create('abcdef12-3456-7890-abcd-ef1234567890', [ 'note' => 'Customer confirmed the withdrawal by phone.', 'mentioned_emails' => ['analyst@example.com'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.transactions.notes.create( "abcdef12-3456-7890-abcd-ef1234567890", note: "Customer confirmed the withdrawal by phone.", mentioned_emails: ["analyst@example.com"] ) 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.Transactions.Notes.CreateAsync("abcdef12-3456-7890-abcd-ef1234567890", new TransactionsNotesCreateParams { Note = "Customer confirmed the withdrawal by phone.", MentionedEmails = new string[] { "analyst@example.com" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: TransactionNote: type: object description: Una nota sulla cronologia di revisione di una transazione monitorata. required: - uuid - note - actor_email - actor_name - metadata - created_at properties: uuid: type: string format: uuid description: Identificatore della nota. note: type: string description: Corpo della nota in testo normale. actor_email: type: string format: email nullable: true description: >- Email dell'utente della Console che ha scritto la nota o modificato lo stato. `null` per le note create con una chiave API e per le note aggiunte automaticamente da Didit. actor_name: type: string nullable: true description: >- Nome visualizzato dell'utente della Console (la sua email se non ha un nome). `Rule Engine` per le note aggiunte automaticamente da Didit. `null` per le note create con una chiave API. metadata: type: object description: >- Distingue le tipologie di note. Le note inserite tramite l'API o la Console includono `mentioned_emails`. Una modifica di stato effettuata nella Console include `type: status_change` con `previous_status`, `new_status`, `reason_code` e `reason_label`. Le note aggiunte da Didit contengono `source`: `rule_action` (con `rule_uuid`) per l'azione `add_note` di una regola, oppure `remediation_session` in caso di errore nella creazione della sessione di verifica dell'azione utente. properties: mentioned_emails: type: array items: type: string format: email description: >- Membri dell'organizzazione menzionati, in lettere minuscole e deduplicati. Vuoto se nessuno è stato menzionato. type: type: string enum: - status_change description: >- Presente sulle note che registrano una modifica di stato effettuata nella Console. previous_status: type: string enum: - APPROVED - IN_REVIEW - DECLINED - AWAITING_USER description: Stato prima della modifica. new_status: type: string enum: - APPROVED - IN_REVIEW - DECLINED - AWAITING_USER description: Stato dopo la modifica. reason_code: type: string nullable: true description: Codice del motivo specificato con la modifica. reason_label: type: string nullable: true description: Etichetta del motivo specificata con la modifica. source: type: string enum: - rule_action - remediation_session description: Presente sulle note aggiunte automaticamente da Didit. rule_uuid: type: string format: uuid description: >- Regola la cui azione `add_note` ha scritto la nota (con `source: rule_action`). created_at: type: string format: date-time description: Quando la nota è stata salvata. 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.