> ## 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 列出受监控交易的备注，按最新排序，包括 API 备注、审核员备注、规则备注和状态变更，支持 limit 与 offset 分页。



列出交易备注 API 提示词
        将提示词复制到剪贴板



      
      

\<pre>

\`List the notes on one Didit monitored transaction through the Management API.

Endpoint:
GET 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: read. Keys limited to specific workflows or to approved sessions cannot call this endpoint.

Goal:
\- Read the review timeline of a transaction (my own API notes, Console reviewer notes, and the notes Didit adds automatically) so I can show it in my back-office or sync it to my case tool.

Path parameter:
\- transaction_id: the Didit transaction uuid returned by POST /v3/transactions/ or GET /v3/transactions/. Not my own txn_id.

Behavior:
\- Notes come back newest first (created_at descending).
\- Paginated with limit (default 50) and offset. count is exact up to 100 and capped at 100 above that, so keep following next until it is null instead of computing pages from count.
\- metadata tells the note types apart: mentioned_emails on notes written through the API or the Console; type "status_change" with previous_status, new_status, reason_code and reason_label when a reviewer changed the status in the Console; source "rule_action" (with rule_uuid) or "remediation_session" on notes Didit adds automatically, which carry actor_name "Rule Engine".

Example call:
curl -X GET "https://verification.didit.me/v3/transactions/{transaction_id}/notes/?limit=50" \
-H "x-api-key: YOUR_API_KEY"

What to read from the response:
\- results[].uuid, note, created_at: the note itself.
\- results[].actor_email and actor_name: the Console user who wrote it. Both are null for notes created with an API key.
\- results[].metadata: mentions and the note type (see Behavior).
\- next: URL of the next page, null on the last page.

Failure modes:
\- 400: limit or offset above 1000000.
\- 401: the API key has expired.
\- 403: missing API key (a wrong, revoked or expired key gets 401) ({"detail": "You do not have permission to perform this action."}), a scoped key without transactions: read, 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 600 GET requests per minute with this key; wait Retry-After seconds and retry.

Side effects: none. This is a pure read.

For the full integration shape, see /integration/integration-prompt.`

\</pre>



      
      

粘贴到

备注记录了交易的分析师时间线，与审核员在 [交易详情](https://docs.didit.me/zh/transaction-monitoring/console.md#交易详情) 中 **备注** 下看到的列表相同。您可以使用 [创建交易备注](https://docs.didit.me/zh/management-api/transactions/create-note.md) 添加自己的备注，并使用 [获取交易](https://docs.didit.me/zh/management-api/transactions/get.md) 读取交易本身，包括其 `activities`。当 `actor_name` 为 `Rule Engine` 时，该备注来自 Didit：可能是规则的 `add_note` [操作](https://docs.didit.me/zh/transaction-monitoring/rules.md#操作)，也可能是为处于 `AWAITING_USER` 状态的交易创建用户操作验证会话时出现问题（会话无法创建，或 Didit 改用了其他工作流）。


## OpenAPI

````yaml zh/openapi-25.json GET /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/:
    get:
      tags:
        - Transactions
      summary: 列出交易备注
      description: >-
        列出单笔受监控交易的备注，按最新优先排序（`created_at` 降序排列）：包括您通过 API
        添加的备注、审核员在控制台中添加的备注和状态变更，以及 Didit 自动添加的备注（规则的 `add_note`
        操作，或创建用户操作验证会话时出现的问题），这些备注带有 `actor_name` 为 `Rule Engine`。`metadata`
        可用于区分不同类型的备注。


        通过 `limit` 和 `offset` 进行分页。`count` 在 100 以内是精确的，超过 100 则上限显示为
        100，因此请持续追踪 `next` 直至其为 `null`，而不要根据 `count` 计算页数。这是一个无副作用的读取操作。


        限定作用域的 API 密钥需要具备 `transactions: read` 权限；限制于某些工作流或已通过会话的密钥无法调用此
        endpoint。审核员可在[交易详情](https://docs.didit.me/zh/transaction-monitoring/console#交易详情)页面的
        **Notes** 下查看相同的列表。
      operationId: list_transaction_notes
      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
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000000
          description: 每页备注数量。默认为 50。非正整数值将回退为 50；大于 1000000 的值将返回 `400`。
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000000
            minimum: 0
            default: 0
          description: 要返回的第一条备注的从零开始的位置。建议跟随 `next`。非整数值将回退为 0；大于 1000000 的值将返回 `400`。
      responses:
        '200':
          description: 一页备注，按最新优先排序。
          content:
            application/json:
              schema:
                type: object
                required:
                  - count
                  - next
                  - previous
                  - results
                properties:
                  count:
                    type: integer
                    description: >-
                      该交易的备注数量：100 以内为准确数值，超过 100 时封顶显示为 100。请依据 `next`
                      进行翻页，而不是据此计算总页数。
                  next:
                    type: string
                    format: uri
                    nullable: true
                    description: 下一页的绝对 URL，最后一页则为 `null`。
                  previous:
                    type: string
                    format: uri
                    nullable: true
                    description: 上一页的绝对 URL，第一页则为 `null`。
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionNote'
              examples:
                API, Console and rule notes:
                  value:
                    count: 3
                    next: null
                    previous: null
                    results:
                      - 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'
                      - uuid: c2222222-3333-4444-8555-666666666666
                        note: >-
                          Status changed from IN_REVIEW to APPROVED. Reason:
                          Source of funds verified
                        actor_email: reviewer@example.com
                        actor_name: Alex Reviewer
                        metadata:
                          type: status_change
                          previous_status: IN_REVIEW
                          new_status: APPROVED
                          reason_code: SOF_VERIFIED
                          reason_label: Source of funds verified
                        created_at: '2026-10-15T17:22:40.103911Z'
                      - uuid: c3333333-4444-4555-8666-777777777777
                        note: >-
                          Large withdrawal to a new wallet: check the source of
                          funds.
                        actor_email: null
                        actor_name: Rule Engine
                        metadata:
                          rule_uuid: d1111111-2222-4333-8444-555555555555
                          source: rule_action
                        created_at: '2026-10-15T08:42:12.004518Z'
                No notes yet:
                  value:
                    count: 0
                    next: null
                    previous: null
                    results: []
        '400':
          description: '`limit` 或 `offset` 超过 1000000。响应体是包含消息的 JSON 数组，而非对象。'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                Limit too large:
                  value:
                    - limit must not exceed 1000000.
                Offset too large:
                  value:
                    - offset must not exceed 1000000.
        '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 read:
                  value:
                    detail: This API key has no read 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：它将返回 `404` HTML 页面，而不是此 JSON 正文。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Not found:
                  value:
                    detail: No Transaction matches the given query.
        '429':
          description: 使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              examples:
                Throttled:
                  value:
                    detail: >-
                      GET request rate limit exceeded. You can make up to 600
                      requests per minute.
          headers:
            Retry-After:
              description: 距离当前一分钟窗口重置的秒数。
              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 GET
            'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/?limit=50'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            for item in client.transactions.notes.list(
                "abcdef12-3456-7890-abcd-ef1234567890",
            ):
                print(item)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            for await (const item of
            didit.transactions.notes.list("abcdef12-3456-7890-abcd-ef1234567890"))
            {
              console.log(item);
            }
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Notes.ListAutoPaging(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            for (var item :
            client.transactions().notes().list("abcdef12-3456-7890-abcd-ef1234567890"))
            {
                System.out.println(item);
            }
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            foreach
            ($didit->transactions->notes->list('abcdef12-3456-7890-abcd-ef1234567890')
            as $item) {
                print_r($item->toArray());
            }
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            didit.transactions.notes.list("abcdef12-3456-7890-abcd-ef1234567890").auto_paging_each
            do |item|
              puts item.to_h
            end
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            await foreach (var item in await
            client.Transactions.Notes.ListAsync("abcdef12-3456-7890-abcd-ef1234567890"))

            {
                Console.WriteLine(JsonSerializer.Serialize(item));
            }
components:
  schemas:
    TransactionNote:
      type: object
      description: 受监控交易的审核时间线上的一条备注。
      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: >-
            Console 用户的显示名称（若未设置姓名则为其邮箱）。对于 Didit 自动添加的备注，显示为 `Rule Engine`。对于使用
            API 密钥创建的备注，为 `null`。
        metadata:
          type: object
          description: >-
            区分不同的备注类型。通过 API 或控制台写入的备注包含 `mentioned_emails`。在控制台中执行的状态变更包含
            `type: status_change` 以及
            `previous_status`、`new_status`、`reason_code` 和 `reason_label`。Didit
            添加的备注包含 `source`：规则的 `add_note` 操作对应 `rule_action`（附带
            `rule_uuid`），而创建用户操作验证会话出现问题时则对应 `remediation_session`。
          properties:
            mentioned_emails:
              type: array
              items:
                type: string
                format: email
              description: 被提及的组织成员，已转为小写并去重。未提及任何人时为空。
            type:
              type: string
              enum:
                - status_change
              description: 在记录 Console 中进行的状态变更的备注中存在。
            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: >-
        您的应用 API 密钥，可在 Business Console 的“开发者 -> API
        密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
        IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
        列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
        URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
        https://docs.didit.me/console/api-keys。

````

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