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

# Crear nota de transacció API

> Afegeix una nota de text pla, amb mencions de membres, a la cronologia de revisió d'una transacció amb Didit des dels vostres sistemes.



Prompt de l'API per crear una nota de transacció
        Copia el prompt al porta-retalls



      
      

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



      
      

Enganxa a

Una nota és context, no una decisió: mai no canvia el `status`, el `score` ni les alertes de la transacció. Els revisors la veuen a **Notes** del [detall de la transacció](https://docs.didit.me/ca/transaction-monitoring/console.md#detall-de-la-transacció) a la Console, i les `activities` de la transacció incorporen una entrada `TRANSACTION_NOTE_ADDED`, que pots llegir amb [Obtenir una transacció](https://docs.didit.me/ca/management-api/transactions/get.md).Com que la nota prové d'una clau d'API, no té autor: `actor_email` i `actor_name` són `null`. Si necessites mostrar qui l'ha escrit, inclou-ho al text de la nota. Llegeix la cronologia completa amb [Llistar les notes de la transacció](https://docs.didit.me/ca/management-api/transactions/list-notes.md).


## OpenAPI

````yaml ca/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 verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/transactions/{transaction_id}/notes/:
    post:
      tags:
        - Transactions
      summary: Crea una nota de transacció
      description: >-
        Afegeix una nota en text pla a la cronologia de revisió d'una transacció
        monitorada, on els revisors de la Console la poden veure. Una nota
        proporciona context, no és una decisió: el `status`, el `score` i les
        alertes de la transacció no canvien, no s'envia cap webhook i no es
        factura res. Les `activities` de la transacció afegeixen una entrada
        `TRANSACTION_NOTE_ADDED`.


        Les notes creades amb una clau d'API no tenen autor: `actor_email` i
        `actor_name` són `null`, de manera que afegeix l'autor al text si el
        necessites. Cada adreça de `mentioned_emails` ha de pertànyer a un
        membre de la teva organització; en cas contrari, tota la sol·licitud
        falla amb `400`; les mencions s'emmagatzemen en minúscules i
        deduplicades, i aquest endpoint no notifica els membres mencionats.


        Cada crida crea una nova nota, per la qual cosa reintentar una
        sol·licitud que ha esgotat el temps d'espera pot afegir-la dues vegades:
        llista les notes abans de reintentar. No hi ha cap endpoint de l'API per
        editar o eliminar una nota. Una clau d'API amb àmbit restringit
        necessita `transactions: write`; una clau limitada a determinats fluxos
        de treball o a sessions aprovades no pot cridar aquest endpoint.
      operationId: create_transaction_note
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: >-
            UUID de transacció de Didit: el `uuid` retornat per `POST
            /v3/transactions/` i `GET /v3/transactions/`. No s'accepta el teu
            propi `txn_id`.
          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 en text pla. Els espais en blanc inicials i finals
                    s'eliminen i es rebutja una nota en blanc. Sense límit de
                    longitud.
                mentioned_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  default: []
                  description: >-
                    Correus electrònics dels membres de la teva organització que
                    cal esmentar. Cadascun ha de ser un correu electrònic vàlid
                    d'un membre de l'organització.
            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 s'ha creat.
          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: >-
            El cos no és vàlid: falta `note`, és nul o està en blanc, hi ha una
            adreça no vàlida a `mentioned_emails` (errors indexats per posició a
            la llista) o una adreça esmentada que no és membre de la teva
            organització. No s'ha creat res.
          content:
            application/json:
              schema:
                type: object
                description: Errors de camp indexats pel nom del camp.
                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 clau d'API ha caducat. Només pot caducar una clau creada amb data
            de caducitat; després d'aquesta data, cada sol·licitud que s'hi faci
            rep una resposta `401`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Expired key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            La sol·licitud no està permesa. Si falta la clau, es rep el missatge
            genèric; una clau incorrecta, revocada o caducada rep un `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: >-
            No existeix cap transacció amb aquest UUID a l'aplicació (no s'ha
            creat mai, s'ha suprimit o pertany a una altra aplicació). Un
            `transaction_id` que no sigui un UUID no arriba a l'API: retorna una
            pàgina HTML `404` en lloc d'aquest cos JSON.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Not found:
                  value:
                    detail: No Transaction matches the given query.
        '429':
          description: >-
            Més de 300 sol·licituds d'escriptura per minut amb aquesta clau
            d'API. Espera el nombre de segons indicat a `Retry-After` i torna-ho
            a provar.
          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: Segons fins que es restableixi la finestra actual d'un minut.
              schema:
                type: integer
                example: 23
            X-RateLimit-Limit:
              description: Sol·licituds permeses per minut en aquest pressupost.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Sol·licituds restants a la finestra actual.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Temps Unix en què es reinicia la finestra.
              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: Una nota a la línia temporal de revisió d'una transacció monitorada.
      required:
        - uuid
        - note
        - actor_email
        - actor_name
        - metadata
        - created_at
      properties:
        uuid:
          type: string
          format: uuid
          description: Identificador de la nota.
        note:
          type: string
          description: Cos de la nota en text pla.
        actor_email:
          type: string
          format: email
          nullable: true
          description: >-
            Correu electrònic de l'usuari de la Console que ha escrit la nota o
            ha canviat l'estat. `null` per a notes creades amb una clau d'API i
            per a notes que Didit afegeix automàticament.
        actor_name:
          type: string
          nullable: true
          description: >-
            Nom visible de l'usuari de la consola (el seu correu electrònic quan
            no té nom). `Rule Engine` en les notes que Didit afegeix
            automàticament. `null` per a notes creades amb una clau d'API.
        metadata:
          type: object
          description: >-
            Distingeix els tipus de notes. Les notes escrites a través de l'API
            o de la consola porten `mentioned_emails`. Un canvi d'estat fet a la
            consola porta `type: status_change` amb `previous_status`,
            `new_status`, `reason_code` i `reason_label`. Les notes que Didit
            afegeix porten `source`: `rule_action` (amb `rule_uuid`) per a
            l'acció `add_note` d'una regla, o `remediation_session` per a un
            problema en crear la sessió de verificació per a l'acció de
            l'usuari.
          properties:
            mentioned_emails:
              type: array
              items:
                type: string
                format: email
              description: >-
                Membres de l'organització esmentats, en minúscules i sense
                duplicats. Buit si no s'ha esmentat ningú.
            type:
              type: string
              enum:
                - status_change
              description: >-
                Present en notes que registren un canvi d'estat fet a la
                consola.
            previous_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Estat abans del canvi.
            new_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Estat després del canvi.
            reason_code:
              type: string
              nullable: true
              description: Codi de motiu facilitat amb el canvi.
            reason_label:
              type: string
              nullable: true
              description: Etiqueta de motiu facilitada amb el canvi.
            source:
              type: string
              enum:
                - rule_action
                - remediation_session
              description: Present en notes que Didit afegeix automàticament.
            rule_uuid:
              type: string
              format: uuid
              description: >-
                Regla l'acció `add_note` de la qual ha escrit la nota (amb
                `source: rule_action`).
        created_at:
          type: string
          format: date-time
          description: Quan es va desar la nota.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau primària té accés complet. Una clau amb nom
        pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
        limitada a determinats fluxos de treball o a sessions aprovades, a una
        llista d'adreces IP i a una data de caducitat. 401 significa que la clau
        és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
        clau, que la clau no té accés a aquest recurs o acció, o que la
        sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
        ruta de sessió significa que la sessió està fora dels fluxos de treball
        o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
        URL d'imatge, vídeo i PDF com a null, i una clau sense permís
        d'escriptura de sessions rep els enllaços de sessió i els tokens com a
        null. Consulta https://docs.didit.me/console/api-keys.

````

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