> ## 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 para crear notas de transacción

> Con la API de Didit, agrega una nota de texto con menciones opcionales de miembros al historial de revisión de una transacción monitorizada.



Prompt de la API para crear una nota de transacción
        Copiar el prompt al portapapeles



      
      

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



      
      

Pegar en

Una nota aporta contexto, no es una decisión: nunca cambia el `status`, el `score` ni las alertas de la transacción. Los revisores la ven en **Notas** del [detalle de la transacción](https://docs.didit.me/es/transaction-monitoring/console.md#detalle-de-la-transacción) de la Console, y las `activities` de la transacción reciben una entrada `TRANSACTION_NOTE_ADDED`, que puedes leer con [Obtener transacción](https://docs.didit.me/es/management-api/transactions/get.md).Como la nota procede de una clave de API, no tiene autor: `actor_email` y `actor_name` son `null`. Si necesitas mostrar quién la escribió, inclúyelo en el texto de la nota. Consulta el historial completo con [Listar notas de transacción](https://docs.didit.me/es/management-api/transactions/list-notes.md).


## OpenAPI

````yaml es/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ón de identidad. Autentícate con el encabezado x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/transactions/{transaction_id}/notes/:
    post:
      tags:
        - Transactions
      summary: Crear nota de transacción
      description: >-
        Añade una nota de texto sin formato a la cronología de revisión de una
        transacción monitorizada, donde la ven los revisores de la Console. Una
        nota es contexto, no una decisión: el `status`, el `score` y las alertas
        de la transacción no cambian, no se envía ningún webhook y no se factura
        nada. Las `activities` de la transacción reciben una entrada
        `TRANSACTION_NOTE_ADDED`.


        Las notas creadas con una clave de API no tienen autor: `actor_email` y
        `actor_name` son `null`, así que incluye el autor en el texto si lo
        necesitas. Cada dirección de `mentioned_emails` debe pertenecer a un
        miembro de tu organización; de lo contrario, toda la solicitud falla con
        `400`. Las menciones se guardan en minúsculas y sin duplicados, y este
        endpoint no notifica a los miembros mencionados.


        Cada llamada crea una nota nueva, así que reintentar una solicitud que
        agotó el tiempo de espera puede añadirla dos veces: lista las notas
        antes de reintentar. No hay ningún endpoint de la API para editar o
        eliminar una nota. Una clave de API con alcance limitado necesita
        `transactions: write`; una clave limitada a algunos flujos o a sesiones
        aprobadas no puede llamar a este endpoint.
      operationId: create_transaction_note
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: >-
            UUID de transacción de Didit: el `uuid` que devuelven `POST
            /v3/transactions/` y `GET /v3/transactions/`. No se acepta tu propio
            `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 texto plano. Se eliminan los espacios en blanco al
                    principio y al final, y se rechaza una nota vacía. Sin
                    límite de longitud.
                mentioned_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  default: []
                  description: >-
                    Correos electrónicos de los miembros de tu organización a
                    los que mencionar. Cada uno debe ser un correo válido de un
                    miembro de la organización.
            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: Se creó la nota.
          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 cuerpo no es válido: falta `note`, es null o está vacío, hay una
            dirección no válida en `mentioned_emails` (errores indexados por
            posición en la lista) o una dirección mencionada que no es miembro
            de tu organización. No se crea nada.
          content:
            application/json:
              schema:
                type: object
                description: Errores de campo indexados por nombre de 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 clave de API ha expirado. Solo puede expirar una clave creada con
            fecha de caducidad; a partir de esa fecha, toda solicitud que la use
            responde `401`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Expired key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            La solicitud no está permitida. Si falta la clave, se recibe el
            mensaje genérico; una clave incorrecta, revocada o expirada recibe
            `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 existe ninguna transacción con este UUID en la aplicación (nunca
            se creó, se eliminó o pertenece a otra aplicación). Un
            `transaction_id` que no es un UUID no llega a la API: devuelve una
            página HTML `404` en lugar de este cuerpo 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 solicitudes de escritura por minuto con esta clave de
            API. Espera el número de segundos indicado en `Retry-After` y vuelve
            a intentarlo.
          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: Segundos hasta que se reinicia la ventana actual de un minuto.
              schema:
                type: integer
                example: 23
            X-RateLimit-Limit:
              description: Solicitudes permitidas por minuto en este presupuesto.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Solicitudes restantes en la ventana actual.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Tiempo Unix en que se restablece la ventana.
              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 en la cronología de revisión de una transacción monitorizada.
      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: Cuerpo de la nota en texto plano.
        actor_email:
          type: string
          format: email
          nullable: true
          description: >-
            Correo electrónico del usuario de la consola que escribió la nota o
            cambió el estado. `null` para las notas creadas con una clave de API
            y para las notas que Didit añade automáticamente.
        actor_name:
          type: string
          nullable: true
          description: >-
            Nombre visible del usuario de la Console (su correo electrónico si
            no tiene nombre). `Rule Engine` en las notas que Didit añade
            automáticamente. `null` en las notas creadas con una clave de API.
        metadata:
          type: object
          description: >-
            Distingue los tipos de nota. Las notas escritas mediante la API o la
            consola incluyen `mentioned_emails`. Un cambio de estado realizado
            en la consola incluye `type: status_change` con `previous_status`,
            `new_status`, `reason_code` y `reason_label`. Las notas que añade
            Didit incluyen `source`: `rule_action` (con `rule_uuid`) para la
            acción `add_note` de una regla, o `remediation_session` para un
            problema al crear la sesión de verificación de acción del usuario.
          properties:
            mentioned_emails:
              type: array
              items:
                type: string
                format: email
              description: >-
                Miembros de la organización mencionados, en minúsculas y sin
                duplicados. Vacío cuando no se mencionó a nadie.
            type:
              type: string
              enum:
                - status_change
              description: >-
                Presente en las notas que registran un cambio de estado
                realizado en la Console.
            previous_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Estado antes del cambio.
            new_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: Estado después del cambio.
            reason_code:
              type: string
              nullable: true
              description: Código de motivo indicado con el cambio.
            reason_label:
              type: string
              nullable: true
              description: Etiqueta de motivo indicada con el cambio.
            source:
              type: string
              enum:
                - rule_action
                - remediation_session
              description: Presente en las notas que Didit añade automáticamente.
            rule_uuid:
              type: string
              format: uuid
              description: >-
                Regla cuya acción `add_note` escribió la nota (con `source:
                rule_action`).
        created_at:
          type: string
          format: date-time
          description: Fecha y hora en que se almacenó la nota.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clave de API de tu aplicación, que encontrarás en Developers -> API
        keys en la Business Console. La clave principal tiene acceso completo.
        Una clave con nombre puede tener un alcance limitado: ninguno, lectura o
        escritura por recurso, limitada a algunos flujos o a sesiones aprobadas,
        a una lista de direcciones IP y a una fecha de caducidad. 401 significa
        que la clave es incorrecta, se revocó o expiró; 403 significa que no se
        envió ninguna clave, que la clave no tiene acceso a este recurso o
        acción, o que la solicitud provino de una dirección fuera de su lista de
        IP; 404 en una ruta de sesión significa que la sesión está fuera de los
        flujos o estados de la clave. Una clave sin acceso a contenido
        multimedia recibe las URL de imágenes, videos y PDF como null, y una
        clave sin permiso de escritura en sesiones recibe los enlaces y tokens
        de sesión como null. Consulta https://docs.didit.me/console/api-keys.

````

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