주소 증명 보고서: 추출된 필드

개요

주소 증명(POA) 인증은 최대 15 MB 크기의 단일 PDF 또는 이미지(TIFF, JPG, JPEG, PNG, WEBP, 선택적으로 ZIP 압축)를 수락하여 문서 유형 분류, LLM 기반 추출 및 PDF/EXIF 포렌식을 실행한 후 다음을 반환합니다.

추출된 주소 — 가공되지 않은 주소와 구조화된 주소(street_1, city, region, postal_code, 위도/경도) 모두 제공.
문서 메타데이터 — 파일 크기, 콘텐츠 유형, 생성 및 수정 날짜, EXIF 날짜, 서명 정보, PDF 포렌식을 통한 오버레이 조작 증거.
인증된 신분증 문서 및 세션 생성 시 제공된 예상 세부 정보와의 이름 일치 점수.
문서가 은행 거래 내역서인 경우 은행 관련 추가 필드(계좌 번호, IBAN, 은행 식별 코드(sort code), 라우팅 번호, SWIFT/BIC, 지점).

추출된 주소 필드 및 문서 유형을 보여주는 Didit 주소 증명 보고서 스크린샷

POA 추출은 비정형 텍스트 읽기를 수행하므로 문서당 5~15초의 지연 시간이 발생합니다. webhook은 전체 워크플로 단계가 완료될 때만 트리거됩니다. 이 시간 동안 결정 endpoint를 5초보다 빠른 주기로 폴링하지 마십시오.

API 응답에 표시되는 위치

결정 endpoint는 GET /v3/session/{sessionId}/decision/에서 POA를 복수형 배열인 poa_verifications[] 로 반환합니다. 각 항목은 워크플로의 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는 기능 수준 상태 enum(FeatureStatusChoices)을 사용합니다.

값	설명
`Not Finished`	이 세션에서 POA 노드가 완료되지 않았습니다(기본 상태).
`Approved`	문서가 정상적으로 파싱되었으며 거부 또는 검토로 확인된 경고가 없습니다.
`In Review`	워크플로에서 하나 이상의 구성 가능한 경고가 검토로 설정되어 있습니다(거부된 항목 없음).
`Declined`	하드 거부 경고가 발생했거나(`MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`), 워크플로에서 구성 가능한 경고가 거부로 설정되어 있습니다.

워크플로 노드에 구성된 맞춤형 상태 규칙을 통해 계산된 상태를 추가로 조정할 수 있으며, 규칙은 거부됨 > 검토 중 > 승인됨의 우선순위로 적용됩니다. 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는 서명 변조를 설명합니다.

QR 코드 및 바코드

모든 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`	사용 가능한 경우 base64 문자열 형식의 디코더 원시 payload, 그렇지 않으면 빈 문자열

지원되는 코드를 찾지 못한 경우 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 오버레이 조작 증거

QR 코드 및 바코드

예시

승인됨 — 은행 거래 내역서

거부됨 — 오버레이 조작 + 이름 불일치

관련 문서

​개요

​API 응답에 표시되는 위치

​스키마

​상태 값

​PDF 오버레이 조작 증거

​QR 코드 및 바코드

​예시

​승인됨 — 은행 거래 내역서

​거부됨 — 오버레이 조작 + 이름 불일치

​관련 문서

개요

API 응답에 표시되는 위치

스키마

상태 값

PDF 오버레이 조작 증거

QR 코드 및 바코드

예시

승인됨 — 은행 거래 내역서

거부됨 — 오버레이 조작 + 이름 불일치

관련 문서