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

# AML 筛查 API：制裁、PEP 与观察名单

> Didit 提供实时 AML 筛查，覆盖 1,300+ 全球观察名单，包括制裁、PEP 与负面新闻。双评分风险体系，每次检查 $0.20，无月度最低消费。



## OpenAPI

````yaml zh/openapi-25.json POST /v3/aml/
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/aml/:
    post:
      tags:
        - Standalone APIs
      summary: AML 筛查（独立）
      description: >-
        通过单次调用筛查个人或企业是否属于 PEP，以及是否列入制裁、警告/观察名单和负面新闻数据集。


        **双分数模型。** 每个命中结果均包含一个 `match_score`（0-100，身份置信度）和一个
        `risk_score`（0-100，实体风险）。`match_score` 低于 `aml_match_score_threshold`（默认
        **93**）的命中项会被标记为 `review_status: "False Positive"` 并在计算风险时予以忽略；其余命中项中的最高
        `risk_score` 将作为 `aml.score`。最终的 `aml.status` 取决于您的阈值配置：`score` >
        `aml_score_review_threshold`（默认 **100**）→ `Declined`；`score` >
        `aml_score_approve_threshold`（默认 **80**）→ `In Review`；否则为 `Approved`。每当
        `score` 非零且 ≥ 通过阈值时，系统会添加 `POSSIBLE_MATCH_FOUND` 警告（分值恰好为 0 时绝不触发警告）。


        **匹配分数权重。** `aml_name_weight` + `aml_dob_weight` + `aml_country_weight`
        的总和必须恰好为 100（默认分别为 60/25/15）。请求中缺失的组成部分将被排除，并对剩余组成部分的权重重新归一化；匹配的
        `document_number` 将作为金钥，直接将 `match_score` 覆盖为 100。


        **延迟。** 普通筛查通常在几秒钟内完成。如果设置了 `include_adverse_media=true`，API
        会等待负面新闻丰富化（初始暂停约 5 秒，外加最长约 25 秒的轮询），请将客户端超时时间配置为**至少 60 秒**。


        **持久化。** `save_api_request` 默认为 **true**：筛查结果将作为会话存储（`request_id` 可用于
        `GET /v3/session/{sessionId}/decision/`），该记录会显示在控制台中，触发 `status.updated`
        Webhook，且后续可以更新命中项的审核状态。若 `save_api_request=false`，则不存储任何内容，`request_id`
        仅作为临时关联 ID。`include_ongoing_monitoring=true` 会对该档案持续进行重新筛查，且必须设置
        `save_api_request=true`（否则强制返回 `400`）。


        **幂等性。** 在发生超时或暂时性错误后重试时，请发送 `Idempotency-Key`
        请求头。该密钥的作用域限定在您的应用和完全相同的请求体。首个完成的请求会存储其响应；后续相同的重试将返回相同的响应，不会执行也不会对另一笔
        AML 筛查计费。如果原始请求仍在运行，请稍后使用相同的密钥重试。如果相同的密钥与不同的请求体一起重复使用，API 将返回 `409`。


        **计费。** 首次成功筛查后将扣除一个 AML API 额度。重放的幂等响应不会再次扣费；余额不足时，系统会在执行任何新筛查之前返回
        `403`。


        **沙盒。** 沙盒应用的密钥会完全跳过筛查和计费，并返回模拟结果：除非您传入 `sandbox_scenario`，否则均为 0 个命中项的
        `Approved`。`save_api_request` 在沙盒密钥上的表现与生产环境密钥相同，因此保存的沙盒筛查可以通过 `GET
        /v3/session/{sessionId}/decision/` 和 `GET
        /v3/session/{sessionId}/generate-pdf/` 检索。
      operationId: post_v3aml
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            可选的重试安全密钥，最多 255
            个字符。使用相同的请求体复用同一密钥将返回原始响应，而不会执行第二次筛查或重复计费。使用不同的请求体复用该密钥将返回 `409`。
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - full_name
              properties:
                full_name:
                  type: string
                  minLength: 2
                  description: >-
                    待筛查个人或企业的姓名。最少 **2
                    个字符**，此为筛查服务商自身的最低限制。在执行任何筛查之前，较短或空白的名称会使该字段返回
                    `400`，因此不会产生任何计费。
                  example: Antonio Ejemplo Modelo
                entity_type:
                  type: string
                  enum:
                    - person
                    - company
                  default: person
                  description: 要筛查的实体类型。默认为 `person`。
                date_of_birth:
                  type: string
                  format: date
                  description: 出生日期（自然人）或成立日期（企业），`YYYY-MM-DD`。通过出生日期权重提高匹配精度。
                  example: '1972-02-29'
                nationality:
                  type: string
                  description: >-
                    ISO 3166-1 **alpha-2** 国家/地区代码（例如 `ES`）。无效代码返回
                    `400`。通过国家/地区权重提高匹配精度。
                  example: ES
                document_number:
                  type: string
                  description: >-
                    身份证件号码。不设权重 — 充当黄金密钥：完全匹配会将命中的 `match_score` 覆盖为
                    100，严重不匹配则会对其进行惩罚扣分。仅当长度为 **2-50
                    个字符**时，才会作为搜索过滤器发送给筛查提供商；超出该范围的值会被接受并存储，筛查仍会运行并计费，只是不会按证件号码缩小范围。
                aml_score_approve_threshold:
                  type: number
                  minimum: 0
                  maximum: 100
                  default: 80
                  description: >-
                    判定结果为 `Approved` 的风险评分阈值（小于或等于该值）。必须 ≤
                    `aml_score_review_threshold`（否则返回 `400`）。
                aml_score_review_threshold:
                  type: number
                  minimum: 0
                  maximum: 100
                  default: 100
                  description: 判定结果为 `Declined` 的风险评分阈值上限。介于两个阈值之间的分数将产生 `In Review`。
                aml_name_weight:
                  type: integer
                  minimum: 0
                  maximum: 100
                  default: 60
                  description: 姓名相似度在单次命中匹配分数中的权重。这三个权重相加必须正好为 100（否则返回 `400`）。
                aml_dob_weight:
                  type: integer
                  minimum: 0
                  maximum: 100
                  default: 25
                  description: 出生日期在单次命中匹配分数中的权重。
                aml_country_weight:
                  type: integer
                  minimum: 0
                  maximum: 100
                  default: 15
                  description: 国家/地区/国籍在单次命中匹配分数中的权重。
                aml_match_score_threshold:
                  type: integer
                  minimum: 0
                  maximum: 100
                  default: 93
                  description: >-
                    逐条命中的截断阈值：`match_score` 低于此值的命中标注为 `False
                    Positive`（不计入风险评估）；等于或高于此值的为 `Unreviewed` 疑似匹配项。
                include_adverse_media:
                  type: boolean
                  default: false
                  description: 同时在新闻媒体中搜索负面报道。汇总结果时最多增加约 30 秒延迟 — 请使用 ≥60 秒的客户端超时时间。
                include_ongoing_monitoring:
                  type: boolean
                  default: false
                  description: >-
                    持续对此档案重新筛查并通过 Webhook 推送变更。需要 `save_api_request=true`（否则返回
                    `400`）。
                save_api_request:
                  type: boolean
                  default: true
                  description: >-
                    将筛查持久化为会话（控制台可见性、决策 endpoint、Webhook、命中审核）。设为 `false`
                    则执行无状态检查。
                vendor_data:
                  type: string
                  description: 您为被筛查用户指定的标识符；将原样返回并与会话一起存储。
                metadata:
                  type: object
                  nullable: true
                  description: 随请求一同存储并回显的自由格式 JSON。
                sandbox_scenario:
                  type: string
                  description: >-
                    仅限沙盒的场景标识（slug）。仅在 API
                    密钥属于沙盒模式应用时被接受；在生产环境应用上会被拒绝。独立筛查没有需要配置的会话，因此 slug
                    直接置于筛查请求本身：`decline_aml_hit` 返回一个具有生产环境格式的命中并将筛查判定为
                    `Declined`，`review_aml_possible_match` 将其判定为 `In
                    Review`，而不触发 AML 结果的场景将使筛查保持无命中。请参阅 GET
                    /v1/sandbox/scenarios/
                    中的场景目录或[沙盒与测试数据](/zh/integration/sandbox-testing)。
                  example: decline_aml_hit
            example:
              full_name: Antonio Ejemplo Modelo
              entity_type: person
              date_of_birth: '1972-02-29'
              nationality: ES
              include_adverse_media: false
              vendor_data: user-1234
      responses:
        '200':
          description: >-
            筛查已完成。`aml.status` 反映您的阈值设置；达到或高于内部收录下限的每个命中项都会列在 `aml.hits`
            中，并带有其身份 `match_score`、实体 `risk_score` 以及解释匹配原因的 `score_breakdown`。
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    format: uuid
                    description: >-
                      当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET
                      /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。
                  aml:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - Approved
                          - In Review
                          - Declined
                        description: >-
                          当 `score` > `aml_score_review_threshold` 时为
                          `Declined`；当 `score` > `aml_score_approve_threshold`
                          时为 `In Review`；否则为 `Approved`（包括没有可用分数的情况）。
                      total_hits:
                        type: integer
                        description: '`hits` 中的条目数量。'
                      entity_type:
                        type: string
                        enum:
                          - person
                          - company
                        description: 回显筛查的实体类型。
                      hits:
                        type: array
                        items:
                          type: object
                          description: >-
                            一个筛查命中项。`match_score` (0–100) 用于衡量身份置信度：低于
                            `aml_match_score_threshold` 的命中项会被标记为
                            `review_status: "False Positive"`
                            并从风险评估中排除；等于或高于该阈值的命中项则为 `"Unreviewed"`
                            的可能匹配。`risk_score` (0–100) 用于衡量匹配实体的风险程度，并决定顶层的
                            `aml.score`。
                          properties:
                            id:
                              type: string
                              nullable: true
                              description: >-
                                Didit 对命中的稳定标识符：`hit_` 后跟 24
                                个十六进制字符。再次对主体进行筛查时，相同的匹配实体保留相同的 `id`。在调用 AML
                                命中审核 endpoint 时作为 `hit_id` 传递。
                            url:
                              type: string
                              nullable: true
                              description: 匹配实体的来源 URL（如有）。
                            match:
                              type: boolean
                              nullable: true
                              description: 旧版精确匹配标志。建议优先使用 `match_score` + `review_status`。
                            score:
                              type: number
                              nullable: true
                              description: 已弃用的加权匹配分数，范围为 0–1。请改用 `match_score`。
                            match_score:
                              type: number
                              nullable: true
                              description: >-
                                身份置信度（0–100）。与 `aml_match_score_threshold`
                                进行比对，以区分误报与可能匹配。
                            risk_score:
                              type: number
                              nullable: true
                              description: >-
                                主体风险评分（0–100）。非误报命中项中的最高 `risk_score` 将成为顶层的
                                `aml.score`。
                            target:
                              type: boolean
                              nullable: true
                            caption:
                              type: string
                              nullable: true
                              description: 匹配实体的显示名称。
                            datasets:
                              type: array
                              nullable: true
                              items:
                                type: string
                                enum:
                                  - PEP
                                  - PEP Level 1
                                  - PEP Level 2
                                  - PEP Level 3
                                  - PEP Level 4
                                  - Sanctions
                                  - Adverse Media
                                  - Warnings and Regulatory Enforcement
                                  - Fitness and Probity
                                  - SIP
                                  - SIE
                                  - Insolvency
                                  - Other Lists
                              description: >-
                                实体被列入的风险类别：`PEP`（及其级别，`PEP Level 1` 至 `PEP Level
                                4`）、`Sanctions`、`Adverse Media`、`Warnings and
                                Regulatory Enforcement`、`Fitness and
                                Probity`、`SIP`、`SIE` 或
                                `Insolvency`。当实体的数据来源未指明上述任何类别时，为 `Other Lists`。
                            features:
                              type: object
                              nullable: true
                            properties:
                              type: object
                              nullable: true
                              description: >-
                                主体档案：`name`、`alias`、`notes`、`gender`、`birthDate`、`birthPlace`、`nationality`、`position`
                                以及其他传记信息数组（均可为空）。
                            rca_name:
                              type: string
                              nullable: true
                              description: 当命中为 RCA 时，用于匹配该实体的相关密切关联人姓名。
                            pep_matches:
                              type: array
                              description: 作为此命中依据的政治公众人物名单条目。
                              items:
                                type: object
                                properties:
                                  list_name:
                                    type: string
                                  publisher:
                                    type: string
                                  source_url:
                                    type: string
                                  description:
                                    type: string
                                  matched_name:
                                    type: string
                                  pep_position:
                                    type: string
                                  date_of_birth:
                                    type: string
                                  place_of_birth:
                                    type: string
                                  aliases:
                                    type: array
                                    items:
                                      type: string
                                  education:
                                    type: array
                                    items:
                                      type: string
                                  other_sources:
                                    type: array
                                    items:
                                      type: string
                            sanction_matches:
                              type: array
                              items:
                                type: object
                              description: 支持此命中的制裁名单条目（底层名单结构与 `pep_matches` 相同，外加制裁专有字段）。
                            warning_matches:
                              type: array
                              items:
                                type: object
                              description: 支持此命中的警告/观察名单条目。
                            adverse_media_matches:
                              type: array
                              description: 负面新闻报道。仅在 `include_adverse_media=true` 时填充。
                              items:
                                type: object
                                properties:
                                  headline:
                                    type: string
                                  summary:
                                    type: string
                                  sentiment:
                                    type: string
                                  sentiment_score:
                                    type: number
                                  source_url:
                                    type: string
                                  thumbnail:
                                    type: string
                                    nullable: true
                                  country:
                                    type: string
                                    nullable: true
                                  author_name:
                                    type: string
                                    nullable: true
                                  publication_date:
                                    type: string
                                    nullable: true
                                  adverse_keywords:
                                    type: array
                                    items:
                                      type: string
                                  other_sources:
                                    type: array
                                    items:
                                      type: string
                            adverse_media_details:
                              type: object
                              nullable: true
                              description: >-
                                实体的负面新闻情感汇总（`sentiment`、`sentiment_score`、`adverse_keywords`
                                频率映射）。仅在 `include_adverse_media=true` 时填充。
                            first_seen:
                              type: string
                              format: date-time
                              nullable: true
                              description: 实体首次出现在数据集中的时间。
                            last_seen:
                              type: string
                              format: date-time
                              nullable: true
                              description: 包含该实体的最新数据集刷新。
                            linked_entities:
                              type: array
                              description: 匹配实体的已知关联关系（家族、关联人、关联公司）。
                              items:
                                type: object
                                properties:
                                  name:
                                    type: array
                                    items:
                                      type: string
                                  active:
                                    type: array
                                    items:
                                      type: string
                                  status:
                                    type: array
                                    items:
                                      type: string
                                  details:
                                    type: array
                                    items:
                                      type: string
                                  relation:
                                    type: array
                                    items:
                                      type: string
                            risk_view:
                              type: object
                              nullable: true
                              description: >-
                                按维度划分的风险明细（`crimes`、`countries`、`categories`、`custom_list`），每个维度均包含
                                `score`、`weightage`、`risk_level` 以及一个
                                `risk_scores` 映射。
                            additional_information:
                              type: object
                              nullable: true
                              description: 自由格式的额外上下文，例如解释实体为何被标记的 `flag_summary` 数组。
                            review_status:
                              type: string
                              nullable: true
                              enum:
                                - False Positive
                                - Unreviewed
                                - Confirmed Match
                                - Inconclusive
                              description: >-
                                `False Positive` — `match_score` 低于
                                `aml_match_score_threshold`，已从风险评估中排除。`Unreviewed`
                                — 等待审核的可能匹配项。`Confirmed Match` / `Inconclusive`
                                — 由审核员（通过 Business
                                Console）针对已保存的会话手动设置；该审核功能不属于本规范的一部分。
                            score_breakdown:
                              type: object
                              nullable: true
                              description: >-
                                `match_score` 的计算方式。姓名、出生日期和国家/地区各自贡献
                                `<component>_score` ×
                                `<component>_weight_normalized`
                                分；当筛查数据中缺少某个组件时，权重会重新归一化。证件号码不参与加权，它充当“金钥”：`MATCH`
                                会将分数直接覆盖为 100，`NEUTRAL` 保持分数不变，`HARD_MISMATCH`
                                会施加惩罚扣分。
                              properties:
                                name_score:
                                  type: integer
                                  nullable: true
                                  description: 原始姓名相似度（0–100）。
                                name_weight:
                                  type: integer
                                  nullable: true
                                  description: 配置的姓名权重（`aml_name_weight`）。
                                name_weight_normalized:
                                  type: number
                                  nullable: true
                                  description: 重新归一化后的名称权重（0–100）。
                                name_contribution:
                                  type: number
                                  nullable: true
                                  description: 姓名对 `total_score` 的贡献点数。
                                dob_score:
                                  type: integer
                                  nullable: true
                                  description: 出生日期分数，为其权重的百分比（−100 至 100）。
                                dob_weight:
                                  type: integer
                                  nullable: true
                                  description: 配置的出生日期权重（`aml_dob_weight`）。
                                dob_weight_normalized:
                                  type: number
                                  nullable: true
                                  description: 重新归一化后的出生日期权重（0–100）。
                                dob_contribution:
                                  type: number
                                  nullable: true
                                  description: 出生日期对 `total_score` 的贡献点数。
                                country_score:
                                  type: integer
                                  nullable: true
                                  description: 国家/地区分数占其权重的百分比（−100 到 100）。
                                country_weight:
                                  type: integer
                                  nullable: true
                                  description: 配置的国家/地区权重（`aml_country_weight`）。
                                country_weight_normalized:
                                  type: number
                                  nullable: true
                                  description: 重新归一化后的国家/地区权重（0–100）。
                                country_contribution:
                                  type: number
                                  nullable: true
                                  description: 国家/地区对 `total_score` 的贡献点数。
                                document_number_match_type:
                                  type: string
                                  nullable: true
                                  enum:
                                    - MATCH
                                    - NEUTRAL
                                    - HARD_MISMATCH
                                  description: 证件号码比对的黄金标准结果。
                                document_number_effect:
                                  type: string
                                  nullable: true
                                  description: 证件号码影响的便于人类阅读的描述。
                                total_score:
                                  type: integer
                                  nullable: true
                                  description: 最终加权匹配分数（0–100），与 `match_score` 保持一致。
                      score:
                        type: number
                        nullable: true
                        description: >-
                          综合 AML 风险评分（0–100）：非误报命中项中的最高 `risk_score`。通过两个阈值驱动
                          `status`。
                      screened_data:
                        type: object
                        description: >-
                          回显筛查的内容：`full_name`、`date_of_birth`、`nationality`、`document_number`（缺失字段为
                          `null`）。
                        properties:
                          full_name:
                            type: string
                          date_of_birth:
                            type: string
                            nullable: true
                          nationality:
                            type: string
                            nullable: true
                          document_number:
                            type: string
                            nullable: true
                      warnings:
                        type: array
                        items:
                          type: object
                          properties:
                            feature:
                              type: string
                              description: 引发该警告的功能。
                            risk:
                              type: string
                              description: 机器可读的风险标识符。
                            additional_data:
                              type: object
                              nullable: true
                              description: 警告的额外上下文（若有）。
                            log_type:
                              type: string
                              description: '`warning`、`information` 或 `error`：风险如何影响结果。'
                            short_description:
                              type: string
                              description: 单行人类可读的摘要。
                            long_description:
                              type: string
                              description: 完整的人类可读解释说明。
                        description: >-
                          当 `score` 不为零且 ≥ `aml_score_approve_threshold` 时包含
                          `POSSIBLE_MATCH_FOUND` 警告（分数刚好为 0 时从不发出警告）；否则为空。
                  vendor_data:
                    type: string
                    nullable: true
                    description: 回显您发送的 `vendor_data`。
                  metadata:
                    type: object
                    nullable: true
                    description: 您发送的 `metadata` 回显。
                  created_at:
                    type: string
                    format: date-time
              examples:
                No hits (Approved):
                  summary: 无异常筛查结果 — 零命中
                  value:
                    request_id: d27c5509-7a66-45a9-b05e-d69d9f4c336a
                    aml:
                      status: Approved
                      total_hits: 0
                      entity_type: person
                      hits: []
                      score: 0
                      screened_data:
                        full_name: Maximilian Mustermann-Doe
                        date_of_birth: '1992-03-14'
                        nationality: DE
                        document_number: null
                      warnings: []
                    vendor_data: user-1234
                    metadata:
                      internal_ref: abc-123
                    created_at: '2026-06-11T10:21:07.013938+00:00'
                PEP hit (Approved — risk below approve threshold):
                  summary: 命中一项政治公众人物疑似匹配；风险评分 73，仍低于默认的通过阈值 80
                  value:
                    request_id: 0b7e7a3e-65a1-4f3d-9c7a-1de2f9a40111
                    aml:
                      status: Approved
                      total_hits: 1
                      entity_type: person
                      hits:
                        - id: hit_7c1e9a40b2d35f86e0a4c912
                          url: https://news.example.org/articles/sample
                          match: false
                          score: 0.93
                          match_score: 93
                          risk_score: 73
                          target: null
                          caption: Antonio Ejemplo Modelo
                          datasets:
                            - PEP Level 1
                            - PEP
                          features: null
                          rca_name: ''
                          first_seen: '2026-01-07T00:00:00'
                          last_seen: '2026-01-07T00:00:00'
                          review_status: Unreviewed
                          properties:
                            name:
                              - Antonio Ejemplo Modelo
                              - Antonio Ejemplo
                            alias:
                              - Antonio Ejemplo Modelo
                              - Ejemplo Modelo, Pedro
                            notes:
                              - Prime Minister of Spain
                            gender:
                              - male
                            birthDate:
                              - '1972-02-29'
                            birthPlace:
                              - Madrid, Spain
                            nationality: null
                            position: null
                          risk_view:
                            crimes:
                              score: 0
                              weightage: 20
                              risk_level: Low
                              risk_scores: {}
                            countries:
                              score: 9.64
                              weightage: 30
                              risk_level: Low
                              risk_scores:
                                Spain: 25.71
                            categories:
                              score: 62.5
                              weightage: 50
                              risk_level: High
                              risk_scores:
                                PEP: 100
                                PEP Level 1: 100
                            custom_list: {}
                          score_breakdown:
                            name_score: 89
                            name_weight: 60
                            name_weight_normalized: 60
                            name_contribution: 53.4
                            dob_score: 100
                            dob_weight: 25
                            dob_weight_normalized: 25
                            dob_contribution: 25
                            country_score: 100
                            country_weight: 15
                            country_weight_normalized: 15
                            country_contribution: 15
                            document_number_match_type: NEUTRAL
                            document_number_effect: No document number provided for screening
                            total_score: 93
                          pep_matches:
                            - aliases: []
                              education: []
                              list_name: Presidency of the Government of Spain
                              publisher: Presidency of the Government of Spain
                              source_url: https://news.example.org/articles/sample
                              description: >-
                                The Presidency of the Government is the central
                                institutional body in Spain that supports the
                                Prime Minister and coordinates the general
                                action of the central government.
                              matched_name: Antonio Ejemplo Modelo
                              pep_position: ''
                              date_of_birth: '1972-02-29'
                              other_sources: []
                              place_of_birth: Madrid, Spain
                          sanction_matches: []
                          warning_matches: []
                          adverse_media_matches: []
                          adverse_media_details: null
                          linked_entities:
                            - name:
                                - Maria Begona Gomez Fernandez
                              active: []
                              status: []
                              details: []
                              relation:
                                - spouse
                          additional_information:
                            flag_summary:
                              - >-
                                Antonio Ejemplo Modelo has been flagged as a
                                Level 1 Politically Exposed Person (PEP) from
                                Spain, serving as the President of the
                                Government of Spain.
                      score: 73
                      screened_data:
                        full_name: Pedro Sanchez Perez-Castejon
                        date_of_birth: '1972-02-29'
                        nationality: ES
                        document_number: null
                      warnings: []
                    vendor_data: null
                    metadata: null
                    created_at: '2026-06-11T10:23:44.812000+00:00'
        '400':
          description: >-
            验证错误。字段级问题返回 DRF 的标准外层结构（每个违规字段一个消息数组）；跨字段规则（权重总和、阈值排序、无保存监控）返回
            `{"error": [...]}`。
          content:
            application/json:
              examples:
                Missing full_name:
                  summary: '`full_name` 是唯一的必填字段'
                  value:
                    full_name:
                      - This field is required.
                Short full_name:
                  summary: '`full_name` 必须至少包含 2 个字符'
                  value:
                    full_name:
                      - Ensure this field has at least 2 characters.
                Invalid nationality:
                  summary: '`nationality` 必须为 ISO 3166-1 alpha-2 代码'
                  value:
                    nationality:
                      - Invalid ISO 3166-1 alpha-2 country code.
                Weights do not sum to 100:
                  summary: >-
                    `aml_name_weight` + `aml_dob_weight` + `aml_country_weight`
                    ≠ 100
                  value:
                    error:
                      - >-
                        AML weights must sum to 100. Current sum: 90 (name: 50,
                        dob: 25, country: 15)
                Thresholds out of order:
                  summary: 通过阈值高于审核阈值
                  value:
                    error:
                      - >-
                        Approve threshold (90.0) cannot be greater than review
                        threshold (80.0)
                Monitoring without saving:
                  summary: '`include_ongoing_monitoring=true` 且 `save_api_request=false`'
                  value:
                    error:
                      - >-
                        Ongoing monitoring can only be enabled when the API
                        request is saved.
        '403':
          description: >-
            权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回
            `401`。缺少密钥时返回 `403` 及 `{"detail": ...}`；错误、已撤销或已过期的密钥返回
            `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{"error": ...}`。
          content:
            application/json:
              examples:
                Missing or invalid API key:
                  summary: 缺少 `x-api-key` 请求头，或者密钥无效/已被吊销
                  value:
                    detail: You do not have permission to perform this action.
                Not enough credits:
                  summary: 组织余额不足以支付本次调用
                  value:
                    error: >-
                      You don't have enough credits to perform this request.
                      Please top up at https://business.didit.me
        '429':
          description: >-
            超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300
            次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含
            `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和
            `Retry-After` 响应头。
          content:
            application/json:
              examples:
                Write rate limit exceeded:
                  summary: 当前分钟内的写入请求超过 300 次
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
              schema:
                type: object
                properties:
                  detail:
                    type: string
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/aml/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -H 'Idempotency-Key: aml-user-1234-2026-08-20' \
              -d '{
                "full_name": "Antonio Ejemplo Modelo",
                "entity_type": "person",
                "date_of_birth": "1972-02-29",
                "nationality": "ES",
                "include_adverse_media": false,
                "vendor_data": "user-1234"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.aml.screen(
                full_name="Antonio Ejemplo Modelo",
                entity_type="person",
                date_of_birth="1972-02-29",
                nationality="ES",
                include_adverse_media=False,
                vendor_data="user-1234",
            )
            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.aml.screen({
              full_name: "Antonio Ejemplo Modelo",
              entity_type: "person",
              date_of_birth: "1972-02-29",
              nationality: "ES",
              include_adverse_media: false,
              vendor_data: "user-1234",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AML.Screen(ctx, didit.AMLScreenParams{\n\tFullName:            \"Antonio Ejemplo Modelo\",\n\tEntityType:          didit.Some(didit.AMLScreenParamsEntityType(\"person\")),\n\tDateOfBirth:         didit.String(\"1972-02-29\"),\n\tNationality:         didit.String(\"ES\"),\n\tIncludeAdverseMedia: didit.Bool(false),\n\tVendorData:          didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import java.time.LocalDate;
            import me.didit.Didit;
            import me.didit.types.AmlScreenParams;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.aml().screen(AmlScreenParams.builder()
                    .fullName("Antonio Ejemplo Modelo")
                    .entityType(AmlScreenParams.EntityType.of("person"))
                    .dateOfBirth(LocalDate.parse("1972-02-29"))
                    .nationality("ES")
                    .includeAdverseMedia(false)
                    .vendorData("user-1234")
                    .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->aml->screen([
                'full_name' => 'Antonio Ejemplo Modelo',
                'entity_type' => 'person',
                'date_of_birth' => '1972-02-29',
                'nationality' => 'ES',
                'include_adverse_media' => false,
                'vendor_data' => 'user-1234',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.aml.screen(
              full_name: "Antonio Ejemplo Modelo",
              entity_type: "person",
              date_of_birth: "1972-02-29",
              nationality: "ES",
              include_adverse_media: false,
              vendor_data: "user-1234"
            )
            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.Aml.ScreenAsync(new AmlScreenParams
            {
                FullName = "Antonio Ejemplo Modelo",
                EntityType = new AmlScreenParamsEntityType("person"),
                DateOfBirth = "1972-02-29",
                Nationality = "ES",
                IncludeAdverseMedia = false,
                VendorData = "user-1234",
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  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.