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

# API de création de note de transaction

> Ajoutez une note en texte brut, avec mentions de membres facultatives, à la chronologie de revue d'une transaction surveillée depuis vos systèmes avec Didit.



Prompt de l'API Create Transaction Note
        Copier le prompt dans le presse-papiers



      
      

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



      
      

Coller dans

Une note apporte du contexte, elle n'est pas une décision : elle ne modifie jamais le `status`, le `score` ni les alertes de la transaction. Les réviseurs la voient sous **Notes** sur le [détail de la transaction](https://docs.didit.me/fr/transaction-monitoring/console.md#détail-d’une-transaction) dans la Console, et les `activities` de la transaction reçoivent une entrée `TRANSACTION_NOTE_ADDED`, que vous pouvez lire avec [Get transaction](https://docs.didit.me/fr/management-api/transactions/get.md).Comme la note provient d'une clé API, elle n'a pas d'auteur : `actor_email` et `actor_name` valent `null`. Si vous devez indiquer qui l'a rédigée, incluez cette information dans le texte de la note. Relisez l'historique complet avec [List transaction notes](https://docs.didit.me/fr/management-api/transactions/list-notes.md).


## OpenAPI

````yaml fr/openapi-25.json POST /v3/transactions/{transaction_id}/notes/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/transactions/{transaction_id}/notes/:
    post:
      tags:
        - Transactions
      summary: Créer une note de transaction
      description: >-
        Ajoutez une note en texte brut à la chronologie d'examen d'une
        transaction surveillée, où les réviseurs de la Console peuvent la voir.
        Une note apporte du contexte et ne constitue pas une décision : le
        `status`, le `score` et les alertes de la transaction ne changent pas,
        aucun webhook n'est envoyé et rien n'est facturé. Le champ `activities`
        de la transaction reçoit une entrée `TRANSACTION_NOTE_ADDED`.


        Les notes créées avec une clé API n'ont pas d'auteur : `actor_email` et
        `actor_name` sont à `null`, indiquez donc l'auteur dans le texte si vous
        en avez besoin. Chaque adresse dans `mentioned_emails` doit appartenir à
        un membre de votre organisation, sinon l'ensemble de la requête échoue
        avec une erreur `400` ; les mentions sont enregistrées en minuscules et
        dédupliquées, et cet endpoint n'envoie pas de notification aux membres
        mentionnés.


        Chaque appel crée une nouvelle note, donc réessayer une requête dont le
        délai d'attente a expiré peut l'ajouter deux fois : listez les notes
        avant de réessayer. Il n'existe aucun endpoint API pour modifier ou
        supprimer une note. Une clé API avec restriction de portée nécessite
        `transactions: write` ; une clé limitée à certains workflows ou à des
        sessions approuvées ne peut pas appeler cet endpoint.
      operationId: create_transaction_note
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: "UUID de transaction Didit\_: le `uuid` renvoyé par `POST /v3/transactions/` et `GET /v3/transactions/`. Votre propre `txn_id` n'est pas accepté."
          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: >-
                    Note en texte brut. Les espaces de début et de fin sont
                    supprimés et une note vide est rejetée. Aucune limite de
                    longueur.
                mentioned_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  default: []
                  description: >-
                    E-mails des membres de votre organisation à mentionner.
                    Chacun doit être un e-mail valide d'un membre de
                    l'organisation.
            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 note a été créée.
          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: >-
            Le corps est invalide : `note` manquant, nul ou vide, adresse
            invalide dans `mentioned_emails` (erreurs indexées par position dans
            la liste), ou adresse mentionnée qui ne correspond pas à un membre
            de votre organisation. Rien n'est créé.
          content:
            application/json:
              schema:
                type: object
                description: Erreurs de champ associées par nom de champ.
                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 clé API a expiré. Seule une clé créée avec une date d'expiration
            peut expirer ; après cette date, chaque requête effectuée avec
            celle-ci renvoie `401`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Expired key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            La requête n'est pas autorisée. Une clé manquante reçoit le message
            générique ; une clé erronée, révoquée ou expirée reçoit `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: >-
            Aucune transaction avec cet UUID n'existe dans l'application (jamais
            créée, supprimée ou détenue par une autre application). Un
            `transaction_id` qui n'est pas un UUID n'atteint pas l'API : il
            renvoie une page HTML `404` au lieu de ce corps JSON.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Not found:
                  value:
                    detail: No Transaction matches the given query.
        '429':
          description: >-
            Plus de 300 requêtes d'écriture par minute avec cette clé API.
            Attendez le nombre de secondes indiqué dans `Retry-After`, puis
            réessayez.
          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: >-
                Secondes avant la réinitialisation de la fenêtre actuelle d'une
                minute.
              schema:
                type: integer
                example: 23
            X-RateLimit-Limit:
              description: Requêtes autorisées par minute dans ce budget.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requêtes restantes dans la fenêtre actuelle.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Temps Unix auquel la fenêtre se réinitialise.
              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: Une note dans la chronologie d'examen d'une transaction surveillée.
      required:
        - uuid
        - note
        - actor_email
        - actor_name
        - metadata
        - created_at
      properties:
        uuid:
          type: string
          format: uuid
          description: Identifiant de la note.
        note:
          type: string
          description: Corps de la note en texte brut.
        actor_email:
          type: string
          format: email
          nullable: true
          description: >-
            E-mail de l'utilisateur de la Console ayant rédigé la note ou
            modifié le statut. `null` pour les notes créées avec une clé API et
            pour les notes ajoutées automatiquement par Didit.
        actor_name:
          type: string
          nullable: true
          description: >-
            Nom d'affichage de l'utilisateur de la Console (son e-mail lorsqu'il
            n'a pas de nom). `Rule Engine` pour les notes ajoutées
            automatiquement par Didit. `null` pour les notes créées avec une clé
            API.
        metadata:
          type: object
          description: >-
            Distingue les types de notes. Les notes rédigées via l'API ou la
            Console contiennent `mentioned_emails`. Un changement de statut
            effectué dans la Console contient `type: status_change` avec
            `previous_status`, `new_status`, `reason_code` et `reason_label`.
            Les notes ajoutées par Didit contiennent `source` : `rule_action`
            (avec `rule_uuid`) pour l'action `add_note` d'une règle, ou
            `remediation_session` pour un problème de création de la session de
            vérification d'action utilisateur.
          properties:
            mentioned_emails:
              type: array
              items:
                type: string
                format: email
              description: >-
                Membres de l'organisation mentionnés, en minuscules et
                dédupliqués. Vide si personne n'a été mentionné.
            type:
              type: string
              enum:
                - status_change
              description: >-
                Présent sur les notes enregistrant un changement de statut
                effectué dans la Console.
            previous_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Statut avant la modification.
            new_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Statut après la modification.
            reason_code:
              type: string
              nullable: true
              description: Code du motif indiqué lors de la modification.
            reason_label:
              type: string
              nullable: true
              description: Libellé du motif indiqué lors de la modification.
            source:
              type: string
              enum:
                - rule_action
                - remediation_session
              description: Présent sur les notes ajoutées automatiquement par Didit.
            rule_uuid:
              type: string
              format: uuid
              description: >-
                Règle dont l'action `add_note` a rédigé la note (avec `source:
                rule_action`).
        created_at:
          type: string
          format: date-time
          description: Moment où la note a été enregistrée.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clé API de votre application, issue de Développeurs -> Clés API dans
        la Business Console. La clé principale dispose d'un accès complet. Une
        clé nommée peut être restreinte : aucun, lecture ou écriture par
        ressource, limitée à certains workflows ou aux sessions approuvées, à
        une liste d'adresses IP et à une date d'expiration. 401 signifie que la
        clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a
        été envoyée, que la clé n'a pas accès à cette ressource ou action, ou
        que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur
        une route de session signifie que la session est hors des workflows ou
        des statuts de la clé. Une clé sans accès aux médias reçoit les URL
        d'images, de vidéos et de PDF à null, et une clé sans accès en écriture
        aux sessions reçoit les liens et tokens de session à null. Voir
        https://docs.didit.me/console/api-keys.

````

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