> ## 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. # KYB 응답 스키마: 결정 페이로드 참조 > Didit KYB 결정 페이로드를 주석과 함께 설명합니다: 등기부 확인, 주요 인물, 실소유자 KYC 요약, 문서, AML 스크리닝, 공통 필드. 인증 건당 $2.00부터. 이 페이지는 기업 확인(KYB) 세션의 [`GET /v3/session/{id}/decision/`](https://docs.didit.me/ko/sessions-api/retrieve-session)이 반환하는 전체 페이로드를 설명합니다. 이 엔드포인트는 통합 엔드포인트입니다. 기업 `session_id`를 전달하면 응답에 `session_kind: "business"`와 아래의 기업 전용 기능 배열이 포함됩니다. ## 최상위 구조 ```json theme={null} { "session_id": "bs_01H...", "session_kind": "business", "session_number": 89, "session_url": "https://verify.didit.me/...", "status": "Approved", "status_override": null, "workflow_id": "wf_kyb_standard", "features": ["KYB_REGISTRY", "AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"], "vendor_data": "biz-acme-001", "metadata": { }, "callback": null, "registry_checks": [ ... ], "aml_screenings": [ ... ], "document_verifications": [ ... ], "key_people_checks": [ ... ], "phone_verifications": null, "email_verifications": null, "questionnaire_responses": null, "ip_analyses": null, "reviews": [ ], "decision_trace": { ... }, "linked_records": null, "contact_details": { ... }, "expected_details": null, "created_at": "...", "expires_at": "..." } ``` 모든 기능 배열은 여러 인스턴스를 가질 수 있으며, 각 항목은 그래프 워크플로의 노드 하나를 나타냅니다. null은 이 세션의 워크플로에 해당 기능이 없었음을 의미합니다. ## 공통 최상위 필드 | 필드 | 유형 | 설명 | | - | - | - | | `session_id` | UUID | 고유 세션 식별자 | | `session_kind` | enum | KYB 세션에서는 항상 `"business"`입니다 | | `session_number` | int | 애플리케이션 내에서의 순번 | | `session_url` | URL | 호스팅 인증 링크 | | `status` | enum | 전체 세션 상태([상태](https://docs.didit.me/ko/business-verification/statuses.md) 참조) | | `status_override` | object 또는 null | 검토자가 플랫폼이 설정했을 상태와 다르게 `status`를 직접 설정한 경우의 `{ overridden_at, automatic_status }`입니다(예: 연결된 주요 인물 인증이 거부되었는데 기업을 승인한 경우). 상태가 자동 상태이면 `null`입니다. 수동 승인과 자동 승인을 구분할 때 이 값을 사용하십시오 | | `decision_trace` | object | 결정이 내려진 과정입니다. `status`, `decided_by`(`manual`, `automatic` 또는 `investigator`), `decided_at`, `automatic_status`, `terminal_node_id`, `actor`, `warning_counts`, 그리고 상태를 설정한 경고인 `status_warnings`를 포함합니다 | | `linked_records` | object 또는 null | 세션에 연결된 다른 레코드의 요약입니다. 표시할 내용이 없으면 `null`입니다 | | `workflow_id` | UUID | 이 세션을 구동한 워크플로 | | `features` | 문자열 배열 | 워크플로가 실행한 기능 식별자입니다(예: `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`, `PHONE`, `EMAIL`) | | `vendor_data` | string | 기업에 대한 귀사의 식별자 | | `metadata` | object | 세션 생성 시 첨부한 자유 형식 JSON | | `callback` | URL 또는 null | 인증 완료 후 선택적으로 리디렉션할 URL | | `contact_details` | object 또는 null | `{ email, email_lang, send_notification_emails, phone }`입니다. 흐름에 이메일 또는 전화 알림이 포함된 경우에 설정됩니다 | | `expected_details` | object 또는 null | 생성 시 전달한 기업 예상 데이터입니다. `company_name`, `registry_country`(`XX` 또는 주 단위 등록부의 경우 주를 포함한 `XX-YY`, 예: `US-CA`), `registration_number`를 포함합니다 | | `reviews` | array | 세션에 대한 최신 검토자 메모 | | `created_at`, `expires_at` | ISO 타임스탬프 | — | ## `registry_checks[]` 각 항목은 하나의 법인 등기부 확인입니다(보통 세션당 하나이며, 재귀적 기업 UBO KYB를 사용하는 그래프 워크플로에서는 여러 개일 수 있습니다). ```json theme={null} { "status": "Approved", "node_id": "feature_kyb_registry", "data_resolved": true, "company": { ...see below... }, "ownership_structure": { }, "warnings": [] } ``` | 필드 | 설명 | | - | - | | `status` | 기능 수명 주기 상태(`Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`) | | `node_id` | 이 확인에 대한 그래프 노드 식별자 | | `data_resolved` | 등기부 데이터 로딩이 완료되었거나 사용자가 데이터를 직접 입력한 경우 `true` | | `company` | 전체 등기 페이로드: 아래 **`company` 블록**을 참조하십시오 | | `ownership_structure` | 소유권 계층이 제공될 때 등기부가 입증한 주식 보유 구조입니다. `shareholders[]`와 `beneficial_owners[]`로 구성되며, 각 항목은 `company.beneficial_owners[]`와 동일한 등기 식별 정보 및 지분(`name`, `entity_type`, `roles`, `ownership_min_shares` / `ownership_max_shares` 등)과 정식 `shareholding`을 가집니다. 등기부가 소유권을 입증하지 않으면 `null`입니다. 현재 기록은 `company.beneficial_owners` 및 `company.ownership`에서 확인하십시오. | | `warnings` | 이 등기 확인에 범위가 지정된 구조화된 경고 및 로그 항목입니다. [기업 확인(KYB) 경고](https://docs.didit.me/ko/business-verification/warnings.md)를 참조하십시오. | ### `company` 블록 중첩된 company 객체는 등기부에서 도출된(선택적으로 사용자가 수정한) 법인의 전체 정보입니다: ```json theme={null} { "uuid": "...", "node_id": "feature_kyb_registry", "status": "Approved", "registry_status": "active", "data_resolved": true, "company_name": "Acme Corporation Limited", "registration_number": "12345678", "country_code": "GBR", "company_type": "Private Limited", "incorporation_date": "2010-05-14", "registered_address": "1 Main Street, London EC1A 1AA, United Kingdom", "tax_number": "SAMPLE-TAX-12345", "risk_level": null, "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "Acme Ltd", "nature_of_business": "Software publishing", "registered_capital": "100000 GBP", "website": "https://acme.example", "email": "alex.sample@example.com", "phone": "+15550101000", "legal_entity_identifier": "529900XXXXXXXXXXXXX", "location_of_registration": "London", "vat_number": "GB980780684", "vat_validation_status": "format_valid", "vat_validated_number": "GB980780684", "vat_validation_source": "format_rules", "vat_validated_name": null, "vat_validated_address": null, "vat_checked_at": "2026-04-16T10:10:00Z", "financial_summary": { }, "officers": [ ... ], "beneficial_owners": [ ... ], "addresses": [ { "type": "registered", "address": "1 Main Street, London EC1A 1AA, United Kingdom", "street": "1 Main Street", "city": "London", "postal_code": "EC1A 1AA", "region": null, "country_code": "GB", "description": null } ], "industries": [ { "code": "58290", "description": "Other software publishing", "scheme": "UK SIC 2007", "is_primary": true } ], "accounts": { ... }, "ownership": { "status": "delivered", "tier_requested": "ubo", "tier_delivered": "ubo", "unavailable_reason": null, "direct_ownership_complete": true, "unresolved": [] }, "registry_tier": "ubo", "registry_tier_delivered": "ubo", "registry_ownership_status": "delivered", "registry_monitoring": null, "registry_data": { }, "user_provided_data": { }, "confirmed_by_user_at": "2026-04-16T10:10:00Z", "last_console_edit_at": null, "is_editable": false } ``` | 필드 | 설명 | | - | - | | `registry_status` | 제공자가 보고한 상태(`active`, `dissolved`, `struck_off`, `inactive` 등). [상태](https://docs.didit.me/ko/business-verification/statuses.md#레지스트리-상태-제공자-제공)를 참조하십시오. | | `is_from_registry` | 데이터가 공식 등기부에서 왔으면 `true`, 수동 입력이면 `false` | | `fetch_status` | `pending`, `resolved`, 또는 `failed`: 등기 조회 상태 | | `verification_status` | `verified`, `failed`, 또는 `unknown` | | `risk_level` | 등기 출처에서 전달되는 선택적 값입니다. 보통 `null`입니다. Didit은 위험 수준을 계산하지 않으므로 판단할 때 `warnings[]`와 세션 `status`를 사용하십시오. | | `registry_monitoring` | 회사의 최신 등기 모니터이며, 없으면 `null`입니다. [등기 모니터링](https://docs.didit.me/ko/business-verification/ownership.md#주주-및-ubo-모니터링)을 사용할 수 있게 된 후에만 채워집니다. 필드: `uuid`, `status`, `unavailable_reason`, `enrolled_at`, `cancelled_at`, `last_bill_date`, `next_bill_date`, `last_event_at`, `events_count`, `watched_fields` | | `is_editable` | 등기 출처 데이터를 최종 사용자가 아직 수정할 수 있으면 `true` | | `registry_data` | Didit의 정규화된 등기 상세 정보입니다. 소유권 결과(`ownership_error`, `section_errors`, `ubo_resolution`), [update-data](https://docs.didit.me/ko/sessions-api/update-data.md)로 적용된 수정 사항, 자체 필드가 없는 등기 사실을 포함합니다. 등기 출처의 원본 기록은 절대 포함하지 않습니다. 키는 회사에 따라 달라지며 안정적인 계약이 아니므로, 정식 필드를 대신 읽으십시오. | | `user_provided_data` | 최종 사용자가 입력하거나 수정한 필드입니다(등기부 값과의 감사 비교에 유용합니다). | | `confirmed_by_user_at` | 최종 사용자가 등기 데이터를 확인하거나 수정한 시각의 타임스탬프입니다. | | `vat_number` | 제출된 VAT 번호(수집된 경우) | | `vat_validation_status` | VAT 번호 검증 결과이며, VAT 번호가 없으면 `tax_number`를 검증한 결과입니다: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate`, 또는 `not_applicable`. [VAT 및 납세자 번호 검증](https://docs.didit.me/ko/business-verification/company-data.md#vat-및-납세자-번호-검증)을 참조하십시오. | | `vat_validated_number` / `vat_validation_source` | 출처가 인식하는 형태로 검사된 번호와, 상태를 결정한 출처(공식 등기부 또는 `format_rules`)입니다. | | `vat_validated_name` / `vat_validated_address` | 출처에 등록된 이름과 주소(출처가 공개하는 경우) | | `vat_checked_at` | 검사 시각의 타임스탬프이며, 검사가 수행되지 않았으면 `null`입니다. | | `officers[]` | 내장된 KYC 보강 정보가 포함된 임원 목록(아래 참조) | | `beneficial_owners[]` | 내장된 KYC 보강 정보가 포함된 UBO 목록(아래 참조) | | `addresses[]` | 등기부가 명시하는 모든 주소이며, 아래 정식 주소 형식을 따릅니다. 명시하는 주소가 없으면 `null`입니다. | | `industries[]` | 등기부가 기업을 분류하는 업종 또는 활동이며, 아래 정식 업종 형식을 따릅니다. 명시하는 활동이 없으면 `null`입니다. | | `accounts` | 보고된 경우 기업 제출 날짜: `last_annual_return_date`와 `last_agm_date`입니다. 이는 재무제표가 아니라 제출 서류와 회의에 관한 날짜입니다. | | `ownership` | 소유권(주주 / UBO) 계층의 결과이며, 아래 정식 형식을 따릅니다. | | `registry_tier` / `registry_tier_delivered` / `registry_ownership_status` | 요청한 계층, 제공되고(과금된) 계층, 소유권 결과입니다. 같은 값이 `ownership`에도 있습니다. | ### 모든 국가와 등기 출처에 대한 단일 형식 Didit은 여러 등기 출처를 통해 많은 국가의 기업 등기부를 읽습니다. 출처마다 고유한 레이아웃을 게시하지만, `company` 블록은 항상 같은 형태를 가집니다. 아래 키는 기업이 어느 국가와 출처에서 왔든 항상 존재하며 타입도 같습니다. 등기부가 게시하지 않는 사실은 `null`이며, 국가에 따라 분기하거나 `registry_data`를 파싱할 필요가 없습니다. 같은 형태가 [결정](https://docs.didit.me/ko/sessions-api/retrieve-session.md), 독립형 [KYB 등기부](https://docs.didit.me/ko/standalone-apis/kyb-registry-ubo.md) 엔드포인트, 호스팅 인증 흐름에서도 반환됩니다. **주소** (`addresses`의 각 항목) | 필드 | 설명 | | - | - | | `type` | 소문자입니다. 등록 사무소는 `registered`이며, 기타 유형은 등기부가 명명한 대로 표기합니다(예: `postal`, `office`). 등기부가 주소의 성격을 밝히지 않으면 `null`입니다. | | `address` | 한 줄로 된 전체 주소입니다. 항상 존재합니다. | | `street`, `city`, `postal_code`, `region` | 등기부가 게시하는 경우 부분별로 나눈 주소입니다. | | `country_code` | ISO 3166-1 alpha-2 | | `description` | 등기부가 제공하는 경우 주소에 대한 등기부 자체 라벨입니다. | **업종** (`industries`의 각 항목) | 필드 | 설명 | | - | - | | `code` | 등기부가 표기하는 그대로의 활동 코드 | | `description` | 등기부가 게시하는 경우의 활동 라벨 | | `scheme` | 분류 체계입니다. 보고한 출처와 관계없이 체계마다 하나의 이름을 사용합니다(`UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`). 기타 국가 체계는 등기부가 사용하는 고유 이름을 유지하며, 등기부가 명명하지 않으면 `null`입니다. | | `is_primary` | `true`는 주요 활동을 뜻합니다. 주요 활동은 정확히 하나입니다 | 등록부에 활동은 있지만 사업 설명이 없으면, `nature_of_business`는 활동 레이블로 채워집니다. 연락처 정보와 다른 명칭은 확인할 수 있을 때 채워지며, 사용자나 검토자가 직접 수정한 내용은 항상 우선합니다. **소유구조** (`ownership`) | 필드 | 설명 | | - | - | | `status` | `delivered`는 제공됨을 뜻합니다. `not_held`는 소유 구조 등록부가 응답했지만 이 회사를 전혀 나열하지 않아 제공할 소유 기록이 없음을 뜻합니다. `unavailable`은 다른 이유로 데이터가 제공되지 않은 경우입니다(소유자를 명시하지 않은 기록, 반환되지 않은 소유 섹션, 조회할 수 없었던 공급업체 포함). `pending`은 등록부가 소유 섹션을 아직 가져오는 중임을 뜻합니다. `not_requested`는 기본 등급에서의 상태입니다 | | `tier_requested` / `tier_delivered` | `basic`, `shareholders` 또는 `ubo`입니다. UBO 요청에 직접 주주 정보만 응답된 경우, `shareholders`로 제공되고 청구됩니다 | | `unavailable_reason` | 요청한 소유 등급이 제공되지 않은 이유입니다. `no_owners_on_record`, `no_natural_person_owner`, `ownership_section_unavailable`, `company_not_found`, `ambiguous_company_match`, `missing_registration_number`, `entity_type_not_covered`, `provider_unavailable` 또는 `other`입니다. 소유 정보가 제공된 경우에는 `null`입니다 | | `direct_ownership_complete` | 직접 주주의 명시된 지분을 합산하면 100%(반올림 오차 1퍼센트포인트 이내)가 되면 `true`, 그렇지 않으면 `false`입니다. 소유 정보가 제공되지 않았거나 지분이 명시되지 않은 경우에는 `null`입니다 | | `unresolved[]` | 등록부가 확인하지 못한 소유 체인의 일부이며, `{ reason, section }` 형식입니다(예: `group_structure`에 대한 `no_group_structure_on_record`는 직접 소유자는 알려져 있지만 그 위의 기업 그룹은 기록에 없음을 뜻합니다) | **등록 상세 정보** (`registry_data`) Didit이 등록 확인에 대해 작성한 세부 정보이며, 등록부 출처의 원본 기록이 아닙니다. 모든 키는 선택 사항이며, 회사에 해당 값이 있을 때에만 포함됩니다. 새로운 키가 추가될 수 있으므로, 위의 기준 필드에서 다루는 항목은 해당 필드를 확인하십시오. | 필드 | 설명 | | - | - | | 등록 정보 (`legal_address`, `registered_address`, `registration_date`, `dissolution_date`, `registry_status`, `verification_status`, `company_type`, 그리고 [update-data](https://docs.didit.me/ko/sessions-api/update-data.md)가 허용하는 기타 필드) | 문자열입니다. update-data로 수정한 내용과, 등록부가 명시했지만 전용 필드가 없는 정보(`registration_date`, `dissolution_date`)입니다 | | `ownership_error` | 요청한 소유 등급이 제공되지 않은 이유이며, `ownership.unavailable_reason`과 같은 코드를 사용합니다(`no_owners_on_record`, `ownership_section_unavailable`, `company_not_found`, `provider_unavailable`, `other` 등) | | `section_errors` | 등록부가 반환하지 않은 섹션을 섹션별로 나타내며(`officers`, `shareholders`, `group_structure`), 각 항목은 `{ status_code }` 형식입니다 | | `ubo_resolution` | UBO 등급이 체인을 따라간 방식입니다. `parent_chain[]`과 `subsidiaries[]`는 `{ name, country_code, registration_number }` 형식이고, `unresolved[]`는 `{ reason, section }` 형식입니다 | | `lite_enrichment` | 같은 국가의 다른 등록부 출처가 채운 Lite 빈 필드입니다. `{ fields[], people_added }` 형식입니다 | | `registry_metadata`, `registry_sources[]`, `previous_names[]`, `parent_companies[]`, `documents_available` | 이전 등록 기록에만 해당합니다. 등록부 자체 필드, 조회한 공식 등록부(`{ name, source_type }` 형식이며 공식 등록부만 명시됩니다), 이전 명칭, 모회사 이름, 사용 가능한 제출 서류 수입니다 | ### 임원 항목 구조 (`company.officers` 내부) ```json theme={null} { "uuid": "...", "name": "Jane Doe", "first_name": "Jane", "last_name": "Doe", "date_of_birth": null, "date_of_birth_year": 1983, "date_of_birth_month": 2, "address": "1 Example Street, London", "appointment_date": "2024-07-01", "termination_date": null, "designation": "Director", "role": "director", "nationality": "USA", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/..." } ``` `date_of_birth`는 등록부가 완전한 날짜를 제공할 때에만 채워집니다. 등록부가 연도나 연월만 제공하면 `date_of_birth_year`와 `date_of_birth_month`를 사용하며, 누락된 일(日)은 추정하지 않습니다. 이름, 출생 정보, 주소, 임명일은 회사 임원 목록과 주요 인물 등록부 목록 모두에서 계속 확인할 수 있습니다. ### 실소유자 항목 구조 (`company.beneficial_owners` 내부) ```json theme={null} { "uuid": "...", "name": "John Doe", "first_name": "John", "last_name": "Doe", "entity_type": "person", "date_of_birth": null, "country_of_birth": null, "email": null, "company_name": null, "registration_number": null, "nationality": null, "designation": null, "appointment_date": null, "voting_min_shares": null, "voting_max_shares": null, "roles": ["ubo"], "ownership_min_shares": "40", "ownership_max_shares": "40", "is_active": true, "kyc_status": "Pending", "kyc_session_url": "https://verify.didit.me/...", "effective_ownership_percent": 40.0, "shareholding": { "share_class": "Ordinary", "number_of_shares": 40, "currency": "GBP", "nominal_value": 1, "total_value": null, "percentage": 40 } } ``` `kyc_status`는 B2C에 안전한 방식으로 매핑됩니다: `Approved`, `Declined` 또는 `Pending`입니다. 전체 세션 상태는 KYC가 완료될 때까지 `Pending`으로 통합됩니다. `shareholding`은 소유자가 보유한 지분을 모든 국가와 등록부 출처에서 같은 형식으로 나타냅니다. 항목은 `share_class`, `number_of_shares`, `currency`, `nominal_value`, `total_value`, `percentage`(정확한 지분율, 소수점 넷째 자리까지)입니다. 등록부에 보유 내역이 없으면 `null`입니다. 영국 PSC의 25-50%와 같은 범위는 지분이 아닙니다. 이 경우 `percentage`는 `null`이고, 범위는 `ownership_min_shares` / `ownership_max_shares`에 그대로 남습니다. 주주와 실소유자는 모두 `beneficial_owners`에 나열되며, `roles`로 구분합니다. ## `key_people_checks[]` 이 항목은 세션의 모든 임원과 실소유자(UBO)에 대한 **집계 검사**입니다. 콘솔에서 "레지스트리에서 추출됨"과 "기업이 제출함"을 나란히 표시할 수 있도록 두 개의 버킷을 제공하며, 상위 수준의 UBO KYC 요약도 함께 제공합니다. ```json theme={null} { "status": "Approved", "node_id": "feature_kyb_key_people", "registry": { "officers": [ ...registry-derived officers... ], "beneficial_owners": [ ...registry-derived UBOs... ] }, "submitted": { "parties": [ ...user-submitted key-people records... ] }, "ubo_kyc_summary": { "total": 2, "approved": 1, "flagged": 0, "pending": 1 }, "warnings": [] } ``` * **`registry.officers` / `registry.beneficial_owners`**: 레지스트리 검사에서 추출된 당사자입니다. * **`submitted.parties`**: 주요 인물 흐름에서 기업 관리자가 직접 추가한 당사자입니다(`source = "USER"` 레코드). ### `registry.officers[]` / `registry.beneficial_owners[]` 레지스트리 정보는 위의 `company.officers` / `company.beneficial_owners`와 일치합니다. 주요 인물 항목에는 AML 상태와 `kyc_session_id`, 인증 워크플로 필드 같은 상세 인증 연결 정보가 추가로 포함됩니다. 회사 목록에는 기존의 단순화된 KYC 상태와 인증 URL이 그대로 유지됩니다. ### `submitted.parties[]` 사용자가 제출한 당사자에는 KYC 또는 하위 KYB 연결 정보가 포함됩니다. ```json theme={null} { "uuid": "...", "entity_type": "person", "name": "Alice Chen", "first_name": "John", "last_name": "Doe", "email": "alex.sample@example.com", "role": "ubo", "ownership_percent": 35.0, "nationality": "USA", "position": "CEO", "date_of_birth": "1990-01-01", "phone_number": "+34612345678", "source": "USER", "requires_verification": true, "is_skipped": false, "kyc_session_id": "sess-xyz...", "kyc_session_status": "Not Started", "kyc_session_url": "https://verify.didit.me/...", "kyc_session_deleted": false, "custom_fields": { } } ``` 법인 당사자(`entity_type: "company"`)에는 법인 UBO에 대해 중첩 KYB가 활성화된 경우 `company_name`, `registration_number`, `kyb_sub_session_id` / `kyb_sub_session_status` / `kyb_sub_session_deleted`가 추가로 포함됩니다. `kyc_session_deleted`(및 이에 대응하는 법인 필드 `kyb_sub_session_deleted`)는 당사자의 하위 세션이 삭제되었을 때 `true`입니다. 삭제된 하위 세션은 삭제 시점의 상태를 그대로 유지하며 절대 완료되지 않으므로, 상태가 아니라 이 플래그를 확인해야 합니다. 해당 `*_session_url`은 링크가 더 이상 연결되지 않기 때문에 `null`로 반환되며, 주요 인물 검사는 무한정 기다리지 않고 `In Review`로 전환됩니다. 하위 세션을 삭제해도 통과로 간주되지 않습니다. KYB가 완료되도록 하려면 [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](https://docs.didit.me/ko/sessions-api/update-data#주요-인물-당사자-건너뛰기)로 해당 당사자를 면제하십시오. ### `ubo_kyc_summary` 전체 UBO KYC 진행 상황으로, 단일 대시보드 카드에 유용합니다. | 필드 | 의미 | | - | - | | `total` | 연결된 KYC 세션이 있는 활성 UBO의 수 | | `approved` | KYC 세션이 `Approved`인 UBO | | `flagged` | KYC 세션이 `Declined` 또는 `In Review`인 UBO | | `pending` | 그 밖의 모든 UBO(아직 완료되지 않음) | 연결된 KYC 세션이 있는 UBO가 없으면 `null`을 반환합니다. ## `document_verifications[]` 노드별로 그룹화된 문서: ```json theme={null} { "status": "Approved", "node_id": "feature_kyb_documents", "items": [ { "uuid": "...", "document_type": "LEGAL_PRESENCE", "document_subtype": "CERTIFICATE_OF_INCORPORATION", "document_group": "LEGAL_PRESENCE", "status": "Approved", "file_url": "https://didit-storage.s3...", "document_metadata": { "file_size": 246810, "content_type": "application/pdf", "creation_date": "2024-05-15", "modified_date": "2024-05-15", "overlay_manipulation": null }, "ocr_data": { "company_name": "Acme Corporation Limited", "registration_number": "12345678", "incorporation_date": "2010-05-14" } } ], "groups": { "LEGAL_PRESENCE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }, "OWNERSHIP_STRUCTURE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }, "required_groups": ["LEGAL_PRESENCE", "OWNERSHIP_STRUCTURE"], "warnings": [] } ``` | 필드 | 설명 | | - | - | | `items[]` | 개별 문서 행입니다. 각 행에는 고유한 `status`, `document_type`, 그룹(`document_group`), `document_subtype`, 서명된 `file_url`, `document_metadata`, OCR 추출 데이터가 포함됩니다. | | `groups` | 그룹 값(`LEGAL_PRESENCE`, `COMPANY_DETAILS`, `OWNERSHIP_STRUCTURE`, `REPRESENTATIVES_AUTHORIZATION`, 그리고 분류되지 않은 문서용 `OTHER`)을 키로 하는 그룹별 진행 카운터입니다. 각 그룹에는 `total`, `approved`, `pending`, `declined`, `in_review`, `other`, `missing`이 포함됩니다. [KYB 문서 그룹](https://docs.didit.me/ko/business-verification/documents.md#문서-그룹)을 참조하십시오. | | `required_groups` | 워크플로에서 필수로 지정한 그룹입니다. 세션 승인은 이 그룹이 모두 충족되어야 진행됩니다. | ### 기업 문서 메타데이터 PDF 기업 문서의 경우, `items[].document_metadata.overlay_manipulation`에 오버레이 텍스트 편집이 의심되는 경우의 포렌식 증거가 포함될 수 있습니다. 이 필드가 있으면 다음 항목이 포함됩니다. | 필드 | 설명 | | - | - | | `analysis_incomplete` | 파일을 끝까지 검사할 수 없을 때만 존재하며 값은 `true`입니다. 검사한 범위의 결과는 가능한 범위에서 유지되며, 해당 문서에는 `KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`가 발생합니다. | | `detected` | 오버레이 텍스트 조작 증거가 감지되었는지 여부입니다. | | `analyzed` | PDF를 분석할 수 있었는지 여부입니다. | | `signals` | 발동된 포렌식 신호입니다(예: `duplicate_font_subset`, `glyph_fragmentation`). | | `manipulated_regions` | 편집이 의심되는 텍스트를 둘러싼 PDF 페이지 좌표 사각형입니다. 구성 요소는 `page`, `x`, `y`, `width`, `height`, `page_width`, `page_height`입니다. | 이 필드는 오버레이 증거가 발견되지 않았을 때, 문서가 PDF가 아닐 때, 또는 PDF를 분석할 수 없었을 때 `null`입니다. ## `aml_screenings[]` 회사 수준의 AML 스크리닝과, 워크플로에 연결된 경우 개인 수준의 AML 스크리닝입니다. ```json theme={null} { "node_id": "feature_aml", "status": "Approved", "total_hits": 0, "score": 0, "entity_type": "COMPANY", "screened_data": { "company_name": "Acme Corporation Limited", "country_code": "GBR" }, "is_ongoing_monitoring_enabled": true, "next_ongoing_monitoring_bill_date": "2027-04-16", "last_ongoing_screening_at": "2026-09-12T04:03:11Z", "last_ongoing_screening_datasets_updated_at": null, "hits": [], "warnings": [] } ``` `total_hits > 0`이면 각 히트에 일치 점수, 위험 점수, 감시 목록 출처가 포함되며, update-aml-hit-status 엔드포인트로 업데이트할 수 있는 히트별 `review_status`도 포함됩니다. 히트 구조는 [AML 스크리닝 보고서](https://docs.didit.me/ko/core-technology/aml-screening/report-aml-screening.md)를 참조하십시오. ## 공유 기능 배열 `phone_verifications`, `email_verifications`, `questionnaire_responses`, `ip_analyses`는 사용자(KYC) 세션과 같은 항목 구조를 사용합니다. 워크플로에 포함되지 않으면 `null`입니다. 항목 스키마는 [KYC 응답](https://docs.didit.me/ko/sessions-api/retrieve-session.md)을 참조하십시오. `signatures`는 워크플로에 [전자 서명](https://docs.didit.me/ko/core-technology/electronic-signature/overview.md) 단계가 있을 때 포함됩니다. 기업 세션에는 회사를 대신해 서명하는 주요 인물마다 항목이 하나씩 있으며, `signer.capacity: "company"`, 회사 이름, 해당 주요 인물의 역할이 포함됩니다. [전자 서명 보고서](https://docs.didit.me/ko/core-technology/electronic-signature/report-electronic-signature.md)를 참조하십시오. ## 경고 기능 그룹 기업 확인(KYB) 경고는 이를 발생시킨 기능별로 그룹화됩니다. * `KYB_REGISTRY`: 레지스트리 가용성, 소유 구조, 회사 활동, 국가 제한 문제에 대한 경고입니다. * `KYB_DOCUMENTS`: 법인 문서 추출, 교차 검증, 메타데이터, 조작, 하위 유형, 연령, 시도 횟수 제한 문제에 대한 경고입니다. * `AML`: 회사 AML 스크리닝 일치 항목 또는 누락된 스크리닝 데이터에 대한 경고입니다. * `KYB_KEY_PEOPLE`: 이사, 임원, UBO 또는 대리인과 관련된 개인 수준 문제에 대한 경고입니다. * `PHONE`: 전화번호 위험, 중복, 차단 목록, 인증 코드 시도 문제에 대한 경고입니다. * `EMAIL`: 이메일 위험, 전달 가능성, 중복, 차단 목록, 인증 코드 시도 문제에 대한 경고입니다. * `QUESTIONNAIRE`: 설문 응답에 따라 작동하는 맞춤 상태 규칙에 대한 경고입니다. * `LOCATION`: 기기 및 IP 분석, 사설 네트워크, IP 차단 목록, 기기 차단 목록, 중복 기기/IP 문제에 대한 경고입니다. * `SIGNATURE`: 전자 서명 거부, 코드 확인 실패, 서명자 이름 불일치, 미검증 서명자, 변경된 문서, 누락된 필드 데이터에 대한 경고입니다. [전자 서명 경고](https://docs.didit.me/ko/core-technology/electronic-signature/warnings-electronic-signature.md)를 참조하십시오. 경고 코드의 전체 목록은 [기업 확인(KYB) 경고](https://docs.didit.me/ko/business-verification/warnings.md)를 참조하십시오. ## 워크플로 기반 필드 필터링 워크플로는 `response_attributes`를 통해 각 기능 항목에 표시될 중첩 필드를 제한할 수 있습니다. `status`, `warnings`, `node_id` 필드는 설정과 관계없이 항상 포함됩니다. 그 외 모든 필드는 허용 목록에 없으면 null로 설정됩니다. 스키마 안정성을 위해 키는 응답에 그대로 남습니다. ## 다음 단계 > [card] [상태](https://docs.didit.me/ko/business-verification/statuses.md) > > 각 상태 값의 의미를 확인하세요. > [card] [위험 평가](https://docs.didit.me/ko/business-verification/risk-assessment.md) > > KYB 결과를 결정하는 요소를 확인하세요. > [card] [AML 보고서](https://docs.didit.me/ko/core-technology/aml-screening/report-aml-screening.md) > > AML 히트 페이로드 전체 참조 문서입니다. > [card] [주요 인물](https://docs.didit.me/ko/business-verification/key-people.md) > > 당사자가 레지스트리 또는 사용자 제출 정보에서 `registry` / `submitted` 버킷으로 나뉘는 방식을 확인하세요. > [card] [문서](https://docs.didit.me/ko/business-verification/documents.md) > > 문서 그룹, OCR 및 상호 참조를 확인하세요. > [card] [세션 조회](https://docs.didit.me/ko/sessions-api/retrieve-session.md) > > 예시 응답을 포함한 전체 엔드포인트 참조 문서입니다. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.