地址证明报告：提取字段详解

概述

地址证明（POA）验证支持单个不超过 15 MB 的 PDF 或图片（TIFF、JPG、JPEG、PNG、WEBP，可选 ZIP 压缩），执行文件类型分类、基于 LLM 的提取以及 PDF/EXIF 取证分析，并返回：

提取的地址 — 包含原始地址和结构化地址（street_1、city、region、postal_code、经纬度）。
文件元数据 — 文件大小、内容类型、创建和修改日期、EXIF 日期、签名信息以及来自 PDF 取证分析的任何叠加层篡改证据。
与已验证的身份证件以及创建会话时提供的预期信息之间的姓名匹配分数。
当文件为银行对账单时的银行相关额外字段（账号、IBAN、排序代码、路由号码、SWIFT/BIC、分支）。

POA 提取会执行非结构化文本读取，这会导致每个文件产生 5–15 秒的延迟。只有在整个工作流步骤完成后才会触发 Webhook — 在此时间窗口内，调用决策 endpoint 的频率请勿高于每 5 秒一次。

在 API 响应中的位置

决策 endpoint 在 GET /v3/session/{sessionId}/decision/ 中以复数数组 poa_verifications[] 的形式返回 POA。每个条目代表工作流中 POA 节点的一次执行；包含多个 POA 步骤（例如银行对账单 + 水电费账单）的会话会为每次执行生成一个条目，并带有各自的 node_id。

GET /v3/session/{sessionId}/decision/
  ──▶ { "poa_verifications": [ { node_id, status, document_type, poa_address, … }, … ] }

下方的结构与规范数据结构一致 — 请参阅数据模型。

数据结构

有关规范数据结构，请参阅数据模型参考中的地址证明。

interface POAV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review';
  node_id: string | null;

  issuing_state: string | null;         // ISO 3166-1 alpha-3
  document_type:                        // never null — falls back to 'UNKNOWN'
    | 'UTILITY_BILL'
    | 'BANK_STATEMENT'
    | 'GOVERNMENT_ISSUED_DOCUMENT'
    | 'OTHER_POA_DOCUMENT'
    | 'UNKNOWN';
  document_subtype: string;             // e.g. 'ELECTRICITY_BILL', 'ACCOUNT_STATEMENT';
                                        // never null — falls back to 'UNKNOWN'
  issuer: string | null;
  issue_date: string | null;            // YYYY-MM-DD
  expiration_date: string | null;       // YYYY-MM-DD when present

  // Extracted address
  poa_address: string | null;           // raw, single-line
  poa_formatted_address: string | null; // geocoded/formatted
  poa_parsed_address: {
    address_type?: string;
    street_1?: string;
    street_2?: string;
    city?: string;
    region?: string;
    postal_code?: string;
    country?: string;                   // ISO 3166-1 alpha-2
    raw_results?: object;
    document_location?: { latitude: number; longitude: number };
  } | null;

  document_file: string | null;         // presigned URL, expires after ~4 hours
  document_language: string | null;     // ISO 639-1, e.g. 'en'
  name_on_document: string | null;

  // Expected details (when supplied at session creation)
  expected_details_address: string | null;
  expected_details_formatted_address: string | null;
  expected_details_parsed_address: object | null;

  // Match scores (float, 0-100)
  name_match_score_expected_details: number | null;
  name_match_score_id_verification: number | null;

  // PDF + image forensics
  document_metadata: {
    file_size: number | null;
    content_type: string | null;
    creation_date: string | null;
    modified_date: string | null;
    creator: string | null;
    producer: string | null;
    software: string | null;
    encryption: string | null;
    is_signed: boolean | null;
    is_tampered: boolean | null;
    signature_info: object | null;
    exif_original_date: string | null;
    exif_digitized_date: string | null;
    processed_by_known_editor: boolean | string | null;
    has_different_creation_mod_date: boolean | null;
    overlay_manipulation: {
      detected: boolean;
      analyzed: boolean;
      signals: string[];                // 'duplicate_font_subset', 'glyph_fragmentation'
      duplicate_font_subsets: object[];
      fragmented_fonts: object[];
      manipulated_regions: {
        page: number;
        x: number;
        y: number;
        width: number;
        height: number;
        page_width: number;
        page_height: number;
      }[];
    } | null;                           // null for non-PDF uploads or when not analyzed
  } | null;

  // Bank-related and custom fields
  extra_fields: {
    bank_account_number: string | null;
    bank_iban: string | null;
    bank_sort_code: string | null;
    bank_routing_number: string | null;
    bank_swift_bic: string | null;
    bank_branch_name: string | null;
    bank_branch_address: string | null;
    document_phone_number: string | null;
    additional_names: string[];
    [customField: string]: unknown;
  };

  extra_files: string[];                // presigned URLs for additional uploaded files

  // QR codes and barcodes
  detected_codes: {
    type: string;                       // 'QR_CODE', 'CODE_128', 'EAN_13', 'DATA_MATRIX', 'PDF_417', …
    page_number: number;                // 1-based
    position: [number, number][] | null;
    x: number | null;
    y: number | null;
    width: number | null;
    height: number | null;
    page_width: number;
    page_height: number;
    raw_payload: string;                // base64, empty string when unavailable
    parsed_payload: unknown | null;      // null when located but undecodable
  }[];

  warnings: Warning[];                  // see Data Models — Warning object
}

warnings[] 中的每个条目都是一个警告对象：{ feature, risk, additional_data, log_type, short_description, long_description, node_id }，对于此报告，feature 始终为 "PROOF_OF_ADDRESS"。

状态值

status 使用功能级状态枚举（FeatureStatusChoices）。

值	含义
`Not Finished`	该会话的 POA 节点尚未完成（默认状态）。
`Approved`	文件解析正常，且没有警告触发拒绝或审核。
`In Review`	针对您工作流的至少一个可配置警告被设为审核（且没有任何拒绝项）。
`Declined`	触发了硬性拒绝警告（`MISSING_ADDRESS_INFORMATION`、`POA_DOCUMENT_EXPIRED`、`INVALID_DOCUMENT_TYPE`、`UNABLE_TO_VALIDATE_DOCUMENT_AGE`），或者针对您工作流的某个可配置警告被设为拒绝。

在工作流节点上配置的自定义状态规则可以进一步调整计算得出的状态；规则按优先级 Declined > In Review > Approved 组合生效。完整风险到操作的映射关系（包括仅限工作流的 FUTURE_ISSUE_DATE 重试行为），请参阅地址证明警告。

PDF 叠加篡改证据

当提交的文件为 PDF 时，document_metadata.overlay_manipulation 可能包含疑似文字叠加的取证证据：

detected：检查发现篡改证据时为 true。
analyzed：PDF 能够被分析时为 true。
analysis_incomplete：仅当文件无法完整检查时存在且为 true。已检查的部分在可能的范围内保留其检查结果，同时文档会触发 POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT。
signals：触发的检查项（duplicate_font_subset、glyph_fragmentation）。
manipulated_regions：围绕疑似被编辑文字的页面坐标矩形。每个矩形使用 PDF 页面坐标空间（x、y、width、height、page_width、page_height），便于审核人员在 PDF 预览中标出受影响的区域。

当文件不是 PDF，或 PDF 无法分析时，该字段为 null。当 detected=true 时，系统还会发出 SUSPECTED_DOCUMENT_MANIPULATION 警告，其 additional_data 与上述信号和矩形信息保持一致。但如果存在更强的信号（数字签名后被修改，即 is_tampered=true），则优先采用该信号，此时 additional_data 描述的是签名篡改情况。

二维码与条形码

每份 POA 报告都包含 detected_codes，涵盖所有已处理的页面。每个条目包含：

字段	描述
`type`	检测到的码制，例如 `QR_CODE`、`CODE_128`、`EAN_13`、`DATA_MATRIX` 或 `PDF_417`
`page_number`	从 1 开始的页码
`position`	渲染页面像素坐标中的检测多边形，无法获得可靠位置时为 `null`
`x`, `y`, `width`, `height`	渲染页面像素坐标中的边界框，无法获得可靠位置时为 `null`
`page_width`, `page_height`	坐标所使用的渲染页面尺寸
`parsed_payload`	解码后的字符串或结构化值，在只能定位码时为 `null`
`raw_payload`	可用时的原始解码器 payload（Base64 字符串）；否则为空字符串

未找到受支持的码时，detected_codes 为空数组。Didit 绝不对 payload 进行猜测：损坏或无法读取的码可能会连同其位置一起返回，且 parsed_payload: null，而码检测失败并不会导致 POA 验证失败。

示例

已通过 — 银行对账单

{
  "poa_verifications": [
    {
      "status": "Approved",
      "node_id": "feature_poa_1",
      "issuing_state": "USA",
      "document_type": "BANK_STATEMENT",
      "document_subtype": "ACCOUNT_STATEMENT",
      "issuer": "National Bank",
      "issue_date": "2026-04-15",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "John A. Smith",
      "poa_address": "123 Main St, Apartment 4B, New York, NY 10001",
      "poa_formatted_address": "123 Main St, Apartment 4B, New York, NY 10001, USA",
      "poa_parsed_address": {
        "address_type": "Street",
        "street_1": "123 Main St",
        "street_2": "Apartment 4B",
        "city": "New York",
        "region": "NY",
        "postal_code": "10001",
        "country": "US",
        "document_location": { "latitude": 40.7128, "longitude": -74.0060 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2026-04-15",
        "modified_date": "2026-04-15",
        "creator": "PDFKit",
        "producer": "Quartz",
        "software": null,
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": false,
        "overlay_manipulation": null
      },
      "name_match_score_expected_details": 100,
      "name_match_score_id_verification": 98,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": "****1234",
        "bank_iban": null,
        "bank_sort_code": null,
        "bank_routing_number": "021000089",
        "bank_swift_bic": "NABNUS33",
        "bank_branch_name": "Manhattan Midtown",
        "bank_branch_address": "111 Wall St, New York, NY",
        "document_phone_number": null,
        "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [
        {
          "type": "QR_CODE",
          "page_number": 1,
          "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
          "x": 820,
          "y": 1120,
          "width": 182,
          "height": 182,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "aHR0cHM6Ly9uYXRpb25hbGJhbmsuZXhhbXBsZS9zdG10Lzk5ODE=",
          "parsed_payload": "https://nationalbank.example/stmt/9981"
        },
        {
          "type": "CODE_128",
          "page_number": 1,
          "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
          "x": 112,
          "y": 1480,
          "width": 448,
          "height": 60,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "MDAxMjM0NTY3ODk=",
          "parsed_payload": "001234567 89"
        }
      ],
      "warnings": []
    }
  ]
}

已拒绝 — 叠加层篡改与姓名不匹配

{
  "poa_verifications": [
    {
      "status": "Declined",
      "node_id": "feature_poa_1",
      "issuing_state": "GBR",
      "document_type": "UTILITY_BILL",
      "document_subtype": "ELECTRICITY_BILL",
      "issuer": "BritishEnergy",
      "issue_date": "2026-03-10",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "JOHN B SMYTH",
      "poa_address": "44 King's Road, London, SW3 4UD",
      "poa_formatted_address": "44 King's Road, London, SW3 4UD, United Kingdom",
      "poa_parsed_address": {
        "street_1": "44 King's Road",
        "city": "London",
        "postal_code": "SW3 4UD",
        "country": "GB",
        "document_location": { "latitude": 51.4880, "longitude": -0.1690 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 412910,
        "content_type": "application/pdf",
        "creation_date": "2026-03-10",
        "modified_date": "2026-05-12",
        "creator": "Adobe Acrobat Pro",
        "producer": "Adobe PDF Library",
        "software": "Adobe Acrobat",
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": true,
        "overlay_manipulation": {
          "detected": true,
          "analyzed": true,
          "signals": ["duplicate_font_subset", "glyph_fragmentation"],
          "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
          "fragmented_fonts": [],
          "manipulated_regions": [
            { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
          ]
        }
      },
      "name_match_score_expected_details": 62,
      "name_match_score_id_verification": 60,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": null, "bank_iban": null, "bank_sort_code": null,
        "bank_routing_number": null, "bank_swift_bic": null,
        "bank_branch_name": null, "bank_branch_address": null,
        "document_phone_number": null, "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [],
      "warnings": [
        {
          "feature": "PROOF_OF_ADDRESS",
          "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
          "additional_data": {
            "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
            "detection_method": "overlay_text_manipulation",
            "signals": ["duplicate_font_subset", "glyph_fragmentation"],
            "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
            "fragmented_fonts": [],
            "manipulated_regions": [
              { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
            ]
          },
          "log_type": "error",
          "short_description": "Suspected document manipulation",
          "long_description": "The system detected signs of potential document manipulation or editing.",
          "node_id": "feature_poa_1"
        },
        {
          "feature": "PROOF_OF_ADDRESS",
          "risk": "NAME_MISMATCH_ID_VERIFICATION",
          "additional_data": {
            "poa_name": "JOHN B SMYTH",
            "kyc_name": "John A. Smith",
            "match_score": 60
          },
          "log_type": "warning",
          "short_description": "Name mismatch with ID verification",
          "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
          "node_id": "feature_poa_1"
        }
      ]
    }
  ]
}

身份认证

验证

监控

平台

地址证明报告：提取字段详解

概述

在 API 响应中的位置

数据结构

状态值

PDF 叠加篡改证据

二维码与条形码

示例

已通过 — 银行对账单

已拒绝 — 叠加层篡改与姓名不匹配

相关内容

​概述

​在 API 响应中的位置

​数据结构

​状态值

​PDF 叠加篡改证据

​二维码与条形码

​示例

​已通过 — 银行对账单

​已拒绝 — 叠加层篡改与姓名不匹配

​相关内容

概述

在 API 响应中的位置

数据结构

状态值

PDF 叠加篡改证据

二维码与条形码

示例

已通过 — 银行对账单

已拒绝 — 叠加层篡改与姓名不匹配

相关内容