> ## 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.

# Transaktionsnotiz per API erstellen

> Mit Didit fügen Sie einer überwachten Transaktion per API eine Klartext-Notiz mit optionalen Erwähnungen von Mitgliedern in der Prüfhistorie hinzu.



Prompt für die API zum Erstellen einer Transaktionsnotiz
        Prompt in die Zwischenablage kopieren



      
      

\<pre>

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

\</pre>



      
      

Einfügen in

Eine Notiz dient als Kontext und ist keine Entscheidung. Sie ändert nie den `status`, den `score` oder die Alerts der Transaktion. Prüfer sehen sie unter **Notizen** in den [Transaktionsdetails](https://docs.didit.me/de/transaction-monitoring/console.md#transaktionsdetails) in der Konsole. Die `activities` der Transaktion erhalten zudem einen Eintrag `TRANSACTION_NOTE_ADDED`, den Sie mit [Transaktion abrufen](https://docs.didit.me/de/management-api/transactions/get.md) auslesen können.Da die Notiz über einen API-Schlüssel erstellt wird, enthält sie keinen Autor: `actor_email` und `actor_name` sind `null`. Wenn Sie anzeigen möchten, wer die Notiz geschrieben hat, nehmen Sie diese Information in den Notiztext auf. Den vollständigen Verlauf rufen Sie mit [Transaktionsnotizen auflisten](https://docs.didit.me/de/management-api/transactions/list-notes.md) ab.


## OpenAPI

````yaml de/openapi-25.json POST /v3/transactions/{transaction_id}/notes/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/transactions/{transaction_id}/notes/:
    post:
      tags:
        - Transactions
      summary: Transaktionsnotiz erstellen
      description: >-
        Fügen Sie der Prüfungs-Timeline einer überwachten Transaktion eine
        Nur-Text-Notiz hinzu, wo Prüfer in der Console sie sehen. Eine Notiz
        liefert Kontext und stellt keine Entscheidung dar: `status`, `score` und
        Alerts der Transaktion ändern sich nicht, es wird kein Webhook gesendet
        und es wird nichts in Rechnung gestellt. Die `activities` der
        Transaktion erhalten einen `TRANSACTION_NOTE_ADDED`-Eintrag.


        Mit einem API-Schlüssel erstellte Notizen haben keinen Autor:
        `actor_email` und `actor_name` sind `null`, tragen Sie den Autor bei
        Bedarf also in den Text ein. Jede Adresse in `mentioned_emails` muss zu
        einem Mitglied Ihrer Organisation gehören, andernfalls schlägt die
        gesamte Anfrage mit `400` fehl; Erwähnungen werden in Kleinbuchstaben
        und dedupliziert gespeichert, und dieser Endpoint benachrichtigt die
        erwähnten Mitglieder nicht.


        Jeder Aufruf erstellt eine neue Notiz, sodass der Wiederholungsversuch
        einer Anfrage nach einem Timeout sie doppelt hinzufügen kann: Listen Sie
        die Notizen vor einem erneuten Versuch auf. Es gibt keinen API-Endpoint
        zum Bearbeiten oder Entfernen einer Notiz. Ein berechtigungsbeschränkter
        API-Schlüssel benötigt `transactions: write`; ein Schlüssel, der auf
        bestimmte Workflows oder genehmigte Sitzungen beschränkt ist, kann
        diesen Endpoint nicht aufrufen.
      operationId: create_transaction_note
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: >-
            Didit-Transaktions-UUID: die von `POST /v3/transactions/` und `GET
            /v3/transactions/` zurückgegebene `uuid`. Ihre eigene `txn_id` wird
            nicht akzeptiert.
          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: >-
                    Klartext-Notiz. Führende und nachgestellte Leerzeichen
                    werden entfernt, und eine leere Notiz wird abgelehnt. Keine
                    Längenbegrenzung.
                mentioned_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  default: []
                  description: >-
                    E-Mail-Adressen von Mitgliedern Ihrer Organisation, die
                    erwähnt werden sollen. Jede muss eine gültige E-Mail-Adresse
                    eines Organisationsmitglieds sein.
            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: Die Notiz wurde erstellt.
          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: >-
            Der Body ist ungültig: `note` fehlt, ist null oder leer, eine
            ungültige Adresse in `mentioned_emails` (Fehler nach Listenposition
            zugeordnet) oder eine erwähnte Adresse, die kein Mitglied Ihrer
            Organisation ist. Es wird nichts erstellt.
          content:
            application/json:
              schema:
                type: object
                description: Feldfehler, indiziert nach Feldname.
                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: >-
            Der API-Schlüssel ist abgelaufen. Nur ein Schlüssel, der mit einem
            Ablaufdatum erstellt wurde, kann ablaufen; nach diesem Datum
            antwortet jede Anfrage damit mit `401`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Expired key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            Die Anfrage ist nicht zulässig. Bei einem fehlenden Schlüssel wird
            die generische Nachricht zurückgegeben; ein falscher, widerrufener
            oder abgelaufener Schlüssel erhält `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: >-
            In der Anwendung existiert keine Transaktion mit dieser UUID (nie
            erstellt, gelöscht oder gehört einer anderen Anwendung). Eine
            `transaction_id`, die keine UUID ist, erreicht die API nicht: Sie
            gibt stattdessen eine `404`-HTML-Seite anstelle dieses JSON-Bodys
            zurück.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Not found:
                  value:
                    detail: No Transaction matches the given query.
        '429':
          description: >-
            Mehr als 300 Schreibanfragen pro Minute mit diesem API-Schlüssel.
            Warten Sie die Anzahl der Sekunden in `Retry-After` ab und führen
            Sie dann einen Wiederholungsversuch durch.
          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: >-
                Sekunden bis zum Zurücksetzen des aktuellen
                Ein-Minuten-Fensters.
              schema:
                type: integer
                example: 23
            X-RateLimit-Limit:
              description: Pro Minute in diesem Budget zulässige Anfragen.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Im aktuellen Zeitfenster verbleibende Anfragen.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix-Zeit, zu der das Zeitfenster zurückgesetzt wird.
              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: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->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: Eine Notiz in der Prüfungs-Timeline einer überwachten Transaktion.
      required:
        - uuid
        - note
        - actor_email
        - actor_name
        - metadata
        - created_at
      properties:
        uuid:
          type: string
          format: uuid
          description: Notizkennung.
        note:
          type: string
          description: Notiztext als Klartext.
        actor_email:
          type: string
          format: email
          nullable: true
          description: >-
            E-Mail des Console-Benutzers, der die Notiz verfasst oder den Status
            geändert hat. `null` für mit einem API-Schlüssel erstellte Notizen
            und für Notizen, die Didit automatisch hinzufügt.
        actor_name:
          type: string
          nullable: true
          description: >-
            Anzeigename des Console-Benutzers (seine E-Mail-Adresse, wenn er
            keinen Namen hat). `Rule Engine` bei Notizen, die Didit automatisch
            hinzufügt. `null` bei Notizen, die mit einem API-Schlüssel erstellt
            wurden.
        metadata:
          type: object
          description: >-
            Unterscheidet die Notiztypen. Über die API oder die Console
            verfasste Notizen enthalten `mentioned_emails`. Eine in der Console
            vorgenommene Statusänderung enthält `type: status_change` mit
            `previous_status`, `new_status`, `reason_code` und `reason_label`.
            Von Didit hinzugefügte Notizen enthalten `source`: `rule_action`
            (mit `rule_uuid`) für die Aktion `add_note` einer Regel oder
            `remediation_session` für ein Problem beim Erstellen der
            Verifizierungssitzung für Benutzeraktionen.
          properties:
            mentioned_emails:
              type: array
              items:
                type: string
                format: email
              description: >-
                Erwähnte Organisationsmitglieder, in Kleinbuchstaben und
                dedupliziert. Leer, wenn niemand erwähnt wurde.
            type:
              type: string
              enum:
                - status_change
              description: >-
                Vorhanden bei Notizen, die eine in der Console vorgenommene
                Statusänderung festhalten.
            previous_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Status vor der Änderung.
            new_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Status nach der Änderung.
            reason_code:
              type: string
              nullable: true
              description: Mit der Änderung angegebener Ursachencode.
            reason_label:
              type: string
              nullable: true
              description: Mit der Änderung angegebene Ursachenbezeichnung.
            source:
              type: string
              enum:
                - rule_action
                - remediation_session
              description: Vorhanden bei Notizen, die Didit automatisch hinzufügt.
            rule_uuid:
              type: string
              format: uuid
              description: >-
                Regel, deren `add_note`-Aktion die Notiz verfasst hat (mit
                `source: rule_action`).
        created_at:
          type: string
          format: date-time
          description: Wann die Notiz gespeichert wurde.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in
        der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter
        Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese-
        oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte
        Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und
        auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen
        oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde,
        der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder
        die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei
        einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows
        oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff
        erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne
        Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als
        null. Siehe https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.