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

> 자체 시스템에서 Didit의 모니터링 대상 거래 검토 타임라인에 일반 텍스트 메모를 추가합니다. 멤버 멘션은 선택 사항입니다.



거래 노트 생성 API 프롬프트
        프롬프트를 클립보드에 복사



      
      

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



      
      

붙여넣을 곳

노트는 맥락 정보일 뿐 결정이 아닙니다. 노트를 추가해도 거래의 `status`, `score`, 알림은 절대 변경되지 않습니다. 검토자는 Console의 [거래 상세](https://docs.didit.me/ko/transaction-monitoring/console.md#거래-상세) 화면에 있는 **노트** 영역에서 노트를 확인할 수 있으며, 거래의 `activities`에는 `TRANSACTION_NOTE_ADDED` 항목이 추가됩니다. 이 항목은 [거래 조회](https://docs.didit.me/ko/management-api/transactions/get.md)로 확인할 수 있습니다.노트는 API 키로 생성되므로 작성자 정보가 없습니다. `actor_email`과 `actor_name`은 `null`입니다. 누가 작성했는지 표시해야 한다면 노트 내용에 그 정보를 포함하세요. 전체 타임라인은 [거래 노트 목록 조회](https://docs.didit.me/ko/management-api/transactions/list-notes.md)로 다시 확인할 수 있습니다.


## OpenAPI

````yaml ko/openapi-25.json POST /v3/transactions/{transaction_id}/notes/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/transactions/{transaction_id}/notes/:
    post:
      tags:
        - Transactions
      summary: 거래 메모 생성
      description: >-
        모니터링 중인 거래의 검토 타임라인에 일반 텍스트 메모를 추가하여 Console 검토자가 볼 수 있도록 합니다. 메모는 맥락
        정보이며 결정이 아닙니다. 거래의 `status`, `score` 및 알림은 변경되지 않고 webhook도 전송되지 않으며
        아무것도 청구되지 않습니다. 거래의 `activities`에 `TRANSACTION_NOTE_ADDED` 항목이 추가됩니다.


        API 키로 생성된 메모에는 작성자가 없습니다. `actor_email` 및 `actor_name`이 `null`이므로 필요한
        경우 텍스트에 작성자를 포함하십시오. `mentioned_emails`의 모든 주소는 조직의 멤버에 속해야 하며, 그렇지 않으면
        전체 요청이 `400`으로 실패합니다. 멘션은 소문자로 변환되어 중복 제거 후 저장되며, 이 endpoint는 멘션된 멤버에게
        알림을 보내지 않습니다.


        각 호출마다 새 메모가 생성되므로 시간 초과된 요청을 재시도하면 메모가 두 번 추가될 수 있습니다. 재시도하기 전에 메모 목록을
        조회하십시오. 메모를 편집하거나 삭제하는 API endpoint는 없습니다. 범위가 지정된 API 키에는
        `transactions: write` 권한이 필요합니다. 일부 워크플로나 승인된 세션으로 제한된 키는 이 endpoint를
        호출할 수 없습니다.
      operationId: create_transaction_note
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: >-
            Didit 거래 UUID: `POST /v3/transactions/` 및 `GET /v3/transactions/`에서
            반환된 `uuid`입니다. 자체 `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: 일반 텍스트 메모입니다. 앞뒤 공백은 잘라내며 빈 메모는 거부됩니다. 길이 제한은 없습니다.
                mentioned_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  default: []
                  description: 멘션할 조직 멤버의 이메일입니다. 각 이메일은 유효한 조직 멤버의 이메일이어야 합니다.
            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: 메모가 생성되었습니다.
          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: >-
            본문이 잘못되었습니다: `note`가 누락되었거나 null이거나 비어 있음, `mentioned_emails`에 잘못된
            주소가 포함됨(목록 위치별 오류 키 지정), 또는 멘션된 주소가 조직의 멤버가 아닙니다. 아무것도 생성되지 않았습니다.
          content:
            application/json:
              schema:
                type: object
                description: 필드 이름을 키로 하는 필드 오류입니다.
                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: >-
            API 키가 만료되었습니다. 만료일이 지정되어 생성된 키만 만료될 수 있으며, 해당 날짜 이후에는 이를 사용한 모든 요청에
            `401`이 반환됩니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Expired key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            요청이 허용되지 않습니다. 키가 누락된 경우 일반 메시지가 반환되며, 잘못되거나 취소되었거나 만료된 키는 `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: >-
            애플리케이션에 이 UUID를 가진 거래가 존재하지 않습니다(생성된 적이 없거나, 삭제되었거나, 다른 애플리케이션 소유임).
            UUID가 아닌 `transaction_id`는 API에 도달하지 않으며, 이 JSON 본문 대신 `404` HTML
            페이지를 반환합니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Not found:
                  value:
                    detail: No Transaction matches the given query.
        '429':
          description: >-
            이 API 키로 분당 300건을 초과하는 쓰기 요청이 발생했습니다. `Retry-After`에 명시된 시간(초)만큼 대기한
            후 다시 시도하세요.
          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: 현재 1분 기간이 초기화될 때까지 남은 시간(초)입니다.
              schema:
                type: integer
                example: 23
            X-RateLimit-Limit:
              description: 이 예산에서 분당 허용되는 요청 수입니다.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: 현재 윈도우에 남은 요청 수입니다.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: 윈도우가 리셋되는 Unix 시간입니다.
              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: 모니터링되는 거래의 검토 타임라인에 있는 메모 1개입니다.
      required:
        - uuid
        - note
        - actor_email
        - actor_name
        - metadata
        - created_at
      properties:
        uuid:
          type: string
          format: uuid
          description: 메모 식별자입니다.
        note:
          type: string
          description: 일반 텍스트 메모 본문입니다.
        actor_email:
          type: string
          format: email
          nullable: true
          description: >-
            메모를 작성하거나 상태를 변경한 Console 사용자의 이메일입니다. API 키로 생성된 메모 및 Didit이 자동으로
            추가한 메모의 경우 `null`입니다.
        actor_name:
          type: string
          nullable: true
          description: >-
            콘솔 사용자의 표시 이름(이름이 없는 경우 이메일)입니다. Didit이 자동으로 추가하는 메모에는 `Rule
            Engine`으로 표시됩니다. API 키로 생성된 메모의 경우 `null`입니다.
        metadata:
          type: object
          description: >-
            메모 유형을 구분합니다. API나 콘솔을 통해 작성된 메모에는 `mentioned_emails`가 포함됩니다. 콘솔에서
            변경된 상태에는 `previous_status`, `new_status`, `reason_code`,
            `reason_label`과 함께 `type: status_change`가 포함됩니다. Didit이 추가하는 메모에는
            규칙의 `add_note` 작업에 대한 `source`: `rule_action`(`rule_uuid` 포함), 또는
            사용자 작업 인증 세션을 생성하는 중 발생한 문제에 대한 `remediation_session`이 포함됩니다.
          properties:
            mentioned_emails:
              type: array
              items:
                type: string
                format: email
              description: 멘션된 조직 멤버 목록으로, 소문자로 변환되고 중복이 제거됩니다. 아무도 멘션되지 않은 경우 비어 있습니다.
            type:
              type: string
              enum:
                - status_change
              description: 콘솔에서 변경된 상태를 기록하는 메모에 표시됩니다.
            previous_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: 변경 전 상태입니다.
            new_status:
              type: string
              enum:
                - APPROVED
                - IN_REVIEW
                - DECLINED
                - AWAITING_USER
              description: 변경 후 상태입니다.
            reason_code:
              type: string
              nullable: true
              description: 변경과 함께 제공된 사유 코드입니다.
            reason_label:
              type: string
              nullable: true
              description: 변경과 함께 제공된 사유 라벨입니다.
            source:
              type: string
              enum:
                - rule_action
                - remediation_session
              description: Didit이 자동으로 추가하는 메모에 표시됩니다.
            rule_uuid:
              type: string
              format: uuid
              description: '`add_note` 작업을 통해 메모를 작성한 규칙(`source: rule_action` 포함).'
        created_at:
          type: string
          format: date-time
          description: 메모가 저장된 시점입니다.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본
        키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며
        특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나
        만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된
        IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를
        벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write
        권한이 없는 키는 세션 링크와 token을 null로 수신합니다.
        https://docs.didit.me/console/api-keys 를 참고하십시오.

````

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