> ## 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 레지스트리 UBO API: 최종 실소유자 조회 > registry 검색에서 얻은 kyb_response_id로 POST /v3/kyb/ubo/를 호출해 소유 구조를 따라 해석된 기업 프로필, 주주, UBO를 조회하세요. Didit API. `POST /v3/kyb/search/`가 후보 기업을 반환한 뒤 **최종 실소유자**가 필요할 때 이 엔드포인트를 사용합니다. 최종 실소유자에는 주주와, 소유 구조를 따라 확인된 자연인 및 모회사가 포함됩니다(`registry_data.ubo_resolution`). 이 요청은 해당 국가의 UBO 가격으로 과금됩니다([국가별 가격](https://docs.didit.me/ko/getting-started/kyb-registry-pricing.md)). 제공되는 등급은 해당 국가와 등기 기관이 제공할 수 있는 가장 높은 등급입니다. `registry_tier_delivered`에는 과금된 등급이 표시됩니다. 보고서에 실소유자로 지정된 자연인이 없으면 `shareholders`가 과금됩니다. 소유 기록이 전혀 없으면 `basic`이 과금되며, 이때 `registry_ownership_status`는 `unavailable`입니다. 소유 정보 출처가 이 기업을 보유하고 있지 않다고 응답한 경우에는 `not_held`입니다([소유 상태](https://docs.didit.me/ko/standalone-apis/kyb-registry.md#소유-구조-상태)). 보고서가 아직 준비 중이거나 소유 구조 섹션을 등기 기관에서 아직 가져오지 않은 경우, 이 엔드포인트는 `202 Accepted`, `kyb_registry.fetch_status: "pending"`, `kyb_registry.registry_ownership_status: "pending"`, `registry_tier_delivered: null`을 반환합니다. 반환된 `request_id`를 보관하고, `registry_checks[0].company.fetch_status`가 `resolved`가 될 때까지 `GET /v3/session/{request_id}/decision/`을 조회하십시오. Didit은 대기 중인 보고서를 자동으로 완료하며, 보고서가 준비되면 제공된 등급에 대해 과금합니다. 대기 중에는 구매 요청을 다시 보내지 마십시오. POST 요청마다 별도의 요청이 생성됩니다. v3에서만 사용할 수 있습니다. `POST /v2/kyb/select/`와 `POST /v3/kyb/select/`는 계약 조건과 가격을 그대로 유지합니다. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/kyb/ubo/ 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/kyb/ubo/: post: tags: - Standalone APIs summary: 실소유자 정보가 포함된 KYB 등기부 기업(독립 실행형) description: >- `POST /v3/kyb/search/`에서 반환된 후보 중 하나의 Lite 프로필, 직접 주주, **그리고 소유 구조 체인을 통해 파악된 최종 실소유자**(`registry_data.ubo_resolution`에 모기업 체인이 포함됨)를 조회합니다. **검색과의 매칭.** 동일한 애플리케이션의 검색에서 반환된 후보의 `kyb_response_id`를 그대로 전달하십시오. 구매하려는 등급(`POST /v3/kyb/search/`의 `tier`)으로 검색해야 합니다. 해당 등급을 제공하는 등기부 체인에서 검색이 실행되며, Lite 검색 결과가 비어 있다고 해서 등기부에 해당 기업이 없다는 증거는 아니기 때문입니다. 해당 국가의 소유 구조 데이터가 다른 등기부에 있는 경우, Didit은 추가 비용 없이 등록번호로 해당 등기부에서 기업을 다시 찾습니다. **결제.** 해당 국가의 UBO 요금으로 청구됩니다([KYB 등기부 요금](/ko/getting-started/kyb-registry-pricing) 참조). 제공되는 등급은 해당 국가 및 등기부에서 제공할 수 있는 최고 등급입니다. 분석된 보고서에서 자연인이 실소유자로 지정되지 않은 경우 주주(Shareholders) 등급이, 소유 구조 기록이 전혀 없는 경우 Lite 등급이 제공되며, `registry_tier_delivered`에 청구된 등급이 명시됩니다. 등기부 호출 전에 UBO 요금 기준으로 잔액을 확인합니다(부족 시 `403`). **지원 여부.** v3 전용입니다. 모든 호출은 기업 세션을 생성합니다(세션 ID는 `request_id`임). **대기 중인 보고서.** 보고서가 아직 준비 중이거나 소유 구조 섹션이 아직 등기부에서 조회되지 않은 경우, 엔드포인트는 202 Accepted, kyb_registry.fetch_status=pending, kyb_registry.registry_ownership_status=pending, registry_tier_delivered=null을 반환합니다. request_id를 보관하고 registry_checks[0].company.fetch_status가 해결될 때까지 GET /v3/session/{request_id}/decision/을 조회하십시오. Didit은 보고서를 자동으로 완료하고 준비가 완료되면 제공된 등급에 대해 요금을 청구합니다. 대기 중인 동안 구매를 반복하지 마십시오. 새로운 POST 호출마다 별도의 요청이 생성됩니다. operationId: post_v3_kyb_ubo parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KYBRegistryCandidateRequest' example: kyb_response_id: 69aeeb95febb0f1704042259 vendor_data: company-1234 responses: '200': description: >- 제공된 등급에 따라 반환되고 청구되는 기업 보고서입니다. 아직 준비 중인 소유 구조 보고서는 202를 반환할 수 있습니다. 저장된 결정을 조회하려면 request_id를 보관하십시오. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- 이 조회에 대해 생성된 기업 세션의 Id입니다. 응답 이후 법인 등기부 조회가 완료되면 저장된 레코드(콘솔에서 확인 가능)가 계속 업데이트됩니다. registry_tier_requested: type: string enum: - basic - shareholders - ubo description: >- 이 endpoint에서 판매하는 등급: select의 경우 `basic` (Lite), `shareholders`, `ubo`입니다. registry_tier_delivered: type: string enum: - basic - shareholders - ubo - null description: >- 실제로 제공되어 결제 청구된 등급입니다. 해당 국가의 등기부에 소유 구조 데이터가 없거나, 등기부에 이 기업의 소유 구조 기록이 없거나, `ubo` 요청의 해결된 보고서에 실소유자로 지정된 자연인이 없는 경우 요청한 등급보다 낮아집니다. nullable: true kyb_registry: type: object description: 전체 등기부 기업 프로필입니다. properties: uuid: type: string format: uuid description: 이 기업 레코드에 대한 Didit의 ID입니다. node_id: type: string example: feature_kyb_registry status: type: string enum: - Not Finished - Approved - Declined - In Review description: >- 법인 등기부 확인에 대한 Didit의 평가입니다(예: 기업이 등기부에서 활성 상태가 아니거나 소유 구조 데이터를 도출할 수 없는 경우 `In Review`). registry_status: type: string nullable: true enum: - active - dissolved - deregistered - see full details - authorised - appointed representative - unauthorised - inactive - no longer authorised - closed - struck off - null description: 등기소에서 보고된 정규화된 기업 상태입니다. data_resolved: type: boolean description: >- 등기소에서 전체 프로필을 반환하면 `true`입니다. 폴링 후에도 등기소에서 여전히 처리 중인 경우 `false`이며, 저장된 레코드는 등기소 처리가 완료되면 자동으로 완료됩니다. company_name: type: string example: Tesco PLC registration_number: type: string nullable: true example: '00445790' country_code: type: string description: ISO 3166-1 alpha-2. example: GB region: type: string nullable: true description: >- 법인 등기부가 지역 단위인 경우 행정 구역 코드(예: `US-CA`의 경우 `CA`), 그렇지 않은 경우 비어 있습니다. company_type: type: string nullable: true example: Public Limited Company incorporation_date: type: string format: date nullable: true example: '1947-11-27' registered_address: type: string nullable: true example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: type: string nullable: true example: GB412 8925 93 risk_level: type: string nullable: true description: 제공되는 경우, 법인 등기부에 보고된 위험 수준입니다. verification_status: type: string enum: - verified - failed - unknown nullable: true description: >- 관할 구역 간 검증 상태: 등기부 상태가 존속 상태(`active`)를 확정하는 경우 `verified`, 회사가 더 이상 존속하지 않음(예: `dissolved`)을 나타내는 경우 `failed`, 그 외의 경우 `unknown`입니다. 등기부에서 가져오지 않은 회사 및 선택이 아직 `pending` 상태인 동안에는 `null`입니다. is_from_registry: type: boolean description: 이 endpoint의 경우 항상 `true`입니다. 프로필을 공식 등기부에서 조회했습니다. fetch_status: type: string enum: - pending - resolved description: 법인 등기부 조회 라이프사이클입니다. `data_resolved`에 반영됩니다. alternative_names: type: string nullable: true description: 보고된 경우, 텍스트 형태의 대체명, 상호명, 이전 명칭 또는 원어 기업명입니다. nature_of_business: type: string nullable: true description: 보고된 경우의 업종 설명 또는 분류 코드입니다. registered_capital: type: string nullable: true registered_capital_amount: type: string nullable: true description: 보고된 경우, 문자열 형태의 십진수 금액입니다. registered_capital_currency: type: string nullable: true description: 보고된 경우의 ISO 4217 코드입니다. website: type: string nullable: true example: https://www.tesco.com/ email: type: string nullable: true example: customer.service@tesco.co.uk phone: type: string nullable: true example: '03301231688' legal_entity_identifier: type: string nullable: true description: 보고된 경우의 LEI입니다. location_of_registration: type: string nullable: true description: 보고된 경우, 기업이 등록된 법인 등기부/관할 구역입니다. vat_number: type: string nullable: true description: >- 호스팅 법인 등기부 단계에서 수집되었거나 이후 편집된 EU VAT 번호입니다. 선택 시점에는 일반적으로 아직 설정되지 않습니다. VAT 및 납세자 번호 검증은 최종 사용자가 호스팅 흐름에서 법인 등기부 단계를 제출할 때 실행됩니다. vat_validation_status: type: string enum: - valid - invalid - format_valid - invalid_format - could_not_validate - not_applicable description: >- 법인 등기부 제출 시 VAT 번호 또는 없는 경우 `tax_number`를 검증한 결과입니다. `valid` / `invalid`: 해당 국가의 공식 등기소(EU VIES, 노르웨이, 스위스, 브라질, 콜롬비아, 코스타리카, 에콰도르, 파라과이, 폴란드의 경우 국내 VAT 등록부 포함)에서 결정됩니다. `format_valid` / `invalid_format`: 등기소 조회가 불가능한 경우 해당 국가의 서식 및 체크 디지트 규칙에 따라 결정됩니다. `could_not_validate`: 등기소를 사용할 수 없습니다. `not_applicable`: 번호가 없거나, 등기소나 규칙이 없는 국가이거나, 샌드박스 세션인 경우입니다. vat_validated_number: type: string nullable: true description: >- 출처가 인식하는 확인된 번호입니다(예: 프랑스 SIREN 또는 네덜란드 RSIN에서 파생된 VAT 번호). 확인이 실행되지 않은 경우 `null`입니다. vat_validation_source: type: string nullable: true enum: - eu_vies - pl_vat_white_list - no_brreg - ch_uid_register - br_receita_federal - co_rues - cr_hacienda - ec_sri - py_dnit - format_rules - null description: >- `vat_validation_status`를 결정한 소스(공식 등기소 또는 `format_rules`)입니다. 검사가 실행되지 않은 경우 `null`입니다. vat_validated_name: type: string nullable: true description: >- 해당 번호를 검증한 소스에 등록된 이름(소스를 통해 공개된 경우). 상태가 `valid`인 경우에만 설정됩니다. vat_validated_address: type: string nullable: true description: >- 번호를 검증한 출처에 등록된 주소(출처에서 제공하는 경우)입니다. 상태가 `valid`일 때만 설정됩니다. vat_checked_at: type: string format: date-time nullable: true description: 검사의 타임스탬프입니다. 검사가 실행되지 않은 경우 `null`입니다. financial_summary: type: object nullable: true description: >- 제공되는 경우, 법인 등기부에 보고된 주식/자본 세부 정보(통화, 총 주식 수, 주식 클래스)입니다. officers: type: array items: type: object properties: uuid: type: string format: uuid name: type: string example: MELISSA BETHELL designation: type: string nullable: true description: '원시 등기 직함(예: `Director`, `Secretary`)입니다.' role: type: string description: >- 직함에서 파생된 정규화된 역할입니다. 17개 값으로 구성된 전체 모델 세트이며, 이 endpoint의 등기부 파싱은 일반적으로 director, non_executive_director, secretary, chairman 또는 company_officer를 내보냅니다. enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - company_officer - settlor - protector - investor - other nationality: type: string nullable: true is_active: type: boolean description: 등기소에서 해당 임명이 사임한 것으로 표시된 경우 `false`. kyc_status: type: string nullable: true enum: - Approved - Declined - Pending - null description: >- 이 임원에 대해 연결된 KYC 세션이 시작된 경우 해당 세션의 상태입니다. 그렇지 않은 경우 `null`입니다. kyc_session_url: type: string nullable: true description: 연결된 KYC 세션이 존재하는 경우 해당 세션의 인증 URL입니다. first_name: type: string nullable: true description: 등기소에서 명시적으로 보고한 경우의 이름입니다. 성명에서 유추되지 않습니다. last_name: type: string nullable: true description: 등기소에서 명시적으로 보고한 경우의 성입니다. address: type: string nullable: true description: 등기부에서 보고된 임원 주소입니다. appointment_date: type: string nullable: true description: 임원이 선임된 날짜입니다. format: date termination_date: type: string nullable: true description: 보고된 경우 선임 종료일입니다. format: date date_of_birth: type: string nullable: true description: >- 법인 등기부에 보고된 전체 생년월일입니다. 출생 연도 또는 월만 알려진 경우 null입니다. format: date date_of_birth_year: type: integer nullable: true minimum: 1 maximum: 9999 description: 전체 날짜를 알 수 없는 경우를 포함하여, 법인 등기부에 보고된 출생 연도입니다. date_of_birth_month: type: integer nullable: true minimum: 1 maximum: 12 description: 법인 등기부에 보고된 출생 월입니다. 연도만 알려진 경우 null입니다. description: 등기부에서 추출된 이사, 비서 및 기타 임원입니다. beneficial_owners: type: array items: type: object properties: uuid: type: string format: uuid name: type: string first_name: type: string nullable: true last_name: type: string nullable: true entity_type: type: string enum: - person - company description: 소유자가 자연인인지 법인인지 여부입니다. roles: type: array items: type: string description: '정규화된 역할입니다(예: `ubo`, `shareholder`).' ownership_min_shares: type: string nullable: true description: '등기소에서 보고한 소유 지분 구간의 하한값(예: `25%`).' ownership_max_shares: type: string nullable: true description: 법인 등기부에서 보고한 소유 구조 구간의 상한선입니다. is_active: type: boolean kyc_status: type: string nullable: true enum: - Approved - Declined - Pending - null kyc_session_url: type: string nullable: true effective_ownership_percent: type: number nullable: true description: >- 파싱된 소유 구조 백분율입니다(최댓값을 사용하고, 최댓값이 없으면 최솟값을 사용합니다). company_name: type: string nullable: true registration_number: type: string nullable: true country_of_birth: type: string nullable: true email: type: string nullable: true nationality: type: string nullable: true designation: type: string nullable: true voting_min_shares: type: string nullable: true voting_max_shares: type: string nullable: true date_of_birth: type: string nullable: true description: 보고된 전체 생년월일입니다. format: date appointment_date: type: string nullable: true description: 신고된 선임일입니다. format: date shareholding: $ref: '#/components/schemas/KYBRegistryShareholding' description: >- 등기부에서 추출한 실소유자 / 중대한 지배력을 가진 자입니다. 등기부에서 소유 구조를 공개하지 않는 경우 비어 있을 수 있습니다. addresses: type: array nullable: true description: 등기부에 기재된 모든 주소의 표준 형식입니다. 기재된 내용이 없으면 null입니다. items: $ref: '#/components/schemas/KYBRegistryAddress' industries: type: array nullable: true description: 등기부에서 기업을 분류하는 표준 형태의 활동입니다. 명시된 활동이 없는 경우 null입니다. items: $ref: '#/components/schemas/KYBRegistryIndustry' accounts: type: object nullable: true additionalProperties: true description: >- 제공되는 경우 법인 등기부 제출 날짜입니다. 연차 보고서 및 주주총회에는 last_annual_return_date 및 last_agm_date를 사용하며, 재무제표와는 구별됩니다. registry_data: $ref: '#/components/schemas/KYBRegistryData' user_provided_data: type: object nullable: true description: >- 이 endpoint에서는 항상 `null`입니다(최종 사용자가 등기부 데이터를 편집할 때 호스팅 KYB 워크플로에서 사용됨). confirmed_by_user_at: type: string format: date-time nullable: true description: 이 endpoint에서는 항상 `null`입니다. last_console_edit_at: type: string format: date-time nullable: true description: 콘솔 검토자가 나중에 기록을 수정할 때 설정됩니다. is_editable: type: boolean description: 법인 등기부에서 가져온 데이터를 호스팅된 플로우/콘솔에서 계속 수정할 수 있는지 여부입니다. registry_tier_delivered: type: string enum: - basic - shareholders - ubo - null description: 최상위 `registry_tier_delivered`와 동일합니다. nullable: true registry_ownership_status: type: string nullable: true enum: - not_requested - delivered - not_held - unavailable - pending - null description: >- 소유 구조 데이터가 반환된 경우 `delivered`, 소유 구조 등기소가 응답했으나 이 기업이 등재되어 있지 않은 경우 `not_held`(`registry_data.ownership_error` 참조), 소유 구조 등급을 요청했으나 등기소에 해당 기업의 데이터가 없거나 조회를 요청할 수 없는 경우 `unavailable`(`registry_data.ownership_error` 참조), 등기소에서 소유 구조 섹션을 아직 가져오지 못해 Didit이 완료 중인 경우 `pending`, Lite 등급인 경우 `not_requested`. ownership: $ref: '#/components/schemas/KYBRegistryOwnership' registry_tier: type: string nullable: true description: >- 워크플로가 주문한 등기소 등급(`basic`, `shareholders` 또는 `ubo`)입니다. `ownership.tier_requested`에도 포함됩니다. registry_monitoring: type: object nullable: true description: 기업의 최신 등기부 모니터링 정보 또는 존재하지 않는 경우 `null`입니다. properties: uuid: type: string format: uuid status: type: string unavailable_reason: type: string nullable: true enrolled_at: type: string format: date-time nullable: true cancelled_at: type: string format: date-time nullable: true last_bill_date: type: string format: date nullable: true next_bill_date: type: string format: date nullable: true last_event_at: type: string format: date-time nullable: true events_count: type: integer watched_fields: description: 모니터가 감시하는 기업 필드입니다. vendor_data: type: string nullable: true description: 전송한 `vendor_data`의 에코 값입니다. metadata: type: object nullable: true description: 전송한 `metadata`의 에코 값입니다. created_at: type: string format: date-time examples: Resolved company: summary: 전체 등기부 프로필(간결성을 위해 임원 목록은 축약됨) value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d node_id: feature_kyb_registry status: In Review registry_status: active data_resolved: true company_name: Tesco PLC registration_number: '00445790' country_code: GB region: '' company_type: Public Limited Company incorporation_date: '1947-11-27' registered_address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: GB412 8925 93 risk_level: low risk verification_status: verified is_from_registry: true fetch_status: resolved alternative_names: TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: https://www.tesco.com/ email: customer.service@tesco.co.uk phone: '03301231688' legal_entity_identifier: null location_of_registration: null financial_summary: currency: Pound (£) total_number_of_shares: '8174378721' meta_detail: Class_Of_Share: Ordinary officers: - uuid: a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b name: CHRISTOPHER JON TAYLOR designation: Secretary role: secretary nationality: null is_active: true kyc_status: null kyc_session_url: null - uuid: b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c name: MELISSA BETHELL designation: Director role: director nationality: British is_active: true kyc_status: null kyc_session_url: null beneficial_owners: [] addresses: - address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA type: legal_entity_registry_address description: registered office address industries: null accounts: last_account: 26 February 2025 next_account: 26 February 2026 due_by_date: 26 August 2026 registry_data: ubo_resolution: parent_chain: [] subsidiaries: [] unresolved: [] user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' '202': description: >- 보고서가 접수되었으며 아직 처리 중입니다. 보고서가 아직 준비 중인 경우 endpoint는 202 Accepted, kyb_registry.fetch_status=pending, registry_tier_delivered=null을 반환합니다. request_id를 유지하고 registry_checks[0].company.fetch_status가 해결될 때까지 GET /v3/session/{request_id}/decision/을 조회하십시오. Didit은 보고서를 자동으로 완료하고 준비가 완료되면 제공된 등급에 대해 요금을 청구합니다. 대기 중인 동안 구매를 반복하지 마십시오. 새로운 POST마다 별도의 요청이 생성됩니다. content: application/json: schema: $ref: 4effa4c0-15af-4a52-8f34-8dbf79be5eee examples: Pending (registry still resolving): summary: 소유 구조 보고서가 아직 처리 중입니다. 저장된 결정을 조회합니다. value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: 7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d node_id: feature_kyb_registry status: Not Finished registry_status: null data_resolved: false company_name: Example Holdings Limited registration_number: '12345678' country_code: HK region: null company_type: null incorporation_date: null registered_address: null tax_number: null risk_level: null verification_status: null is_from_registry: true fetch_status: pending alternative_names: null nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: null email: null phone: null legal_entity_identifier: null location_of_registration: null financial_summary: {} officers: [] beneficial_owners: [] addresses: null industries: null accounts: null registry_data: {} user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true registry_tier_delivered: null registry_ownership_status: pending vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' registry_tier_delivered: null registry_tier_requested: ubo '400': description: 유효성 검사 오류입니다. 필드 수준 문제는 DRF의 표준 엔벨로프를 사용합니다. content: application/json: examples: Missing kyb_response_id: summary: '`kyb_response_id`는 필수 항목입니다.' value: kyb_response_id: - This field is required. save_api_request=false rejected: summary: 선택 항목은 항상 지속됩니다 value: save_api_request: - >- KYB registry select must be saved so billing and retrieval can be tracked. '403': description: >- 권한이 거부되었습니다. `x-api-key` 헤더가 누락되었거나 호출한 조직의 잔액이 호출 비용을 충당할 수 없을 때 반환됩니다. 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 키가 누락된 경우 `{"detail": ...}`과 함께 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 크레딧이 부족한 경우 어떠한 스크리닝이나 제공업체 호출도 진행되기 전에 `{"error": ...}`과 함께 `403`을 반환합니다. 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/kyb/ubo/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.list_ubos( kyb_response_id="69aeeb95febb0f1704042259", vendor_data="company-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.kyb.listUbos({ kyb_response_id: "69aeeb95febb0f1704042259", vendor_data: "company-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListUBOs(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.KYBRegistryCandidateRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.kyb().listUbos(KYBRegistryCandidateRequest.builder() .kybResponseId("69aeeb95febb0f1704042259") .vendorData("company-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- kyb->listUbos([ 'kyb_response_id' => '69aeeb95febb0f1704042259', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.list_ubos( kyb_response_id: "69aeeb95febb0f1704042259", vendor_data: "company-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.Kyb.ListUbosAsync(new KYBRegistryCandidateRequest { KybResponseId = "69aeeb95febb0f1704042259", VendorData = "company-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBRegistryCandidateRequest: type: object required: - kyb_response_id properties: kyb_response_id: type: string maxLength: 1024 description: >- `POST /v3/kyb/search/`의 후보 핸들(`kyb_registry.companies[].kyb_response_id`)입니다. 임시 값이므로 이를 생성한 검색 직후에 사용하십시오. 핸들은 길어질 수 있으므로 잘라내거나 길이를 가정하지 말고 반환된 값을 그대로 저장하고 전송하십시오. example: 69aeeb95febb0f1704042259 vendor_data: type: string description: 해당 기업에 대한 귀하의 식별자입니다. 기업 세션에 저장되며 그대로 다시 반환됩니다. metadata: type: object nullable: true description: 기업 세션과 함께 저장되고 그대로 반환되는 자유 형식 JSON입니다. save_api_request: type: boolean default: true description: >- `true`(기본값)여야 합니다. KYB 등기부 선택 항목은 결제 및 조회를 추적할 수 있도록 항상 유지됩니다. `false`는 `400`을 반환합니다. KYBRegistryShareholding: type: object nullable: true description: >- 모든 국가 및 법인 등기부 출처에 대해 동일한 형식으로 제공되는 소유자의 보유 내역입니다. 등기부에 보유 내역이 명시되어 있지 않은 경우 null입니다. 범위(예: 영국 PSC의 25-50%)는 지분이 아닙니다. `percentage`는 null이며 해당 범위는 `ownership_min_shares` / `ownership_max_shares`에 유지됩니다. properties: share_class: type: string nullable: true description: 등기부에서 명시한 주식 종류 또는 유형입니다. number_of_shares: type: number nullable: true description: 보유 주식 수입니다. currency: type: string nullable: true description: 아래 값의 ISO 4217 통화입니다. nominal_value: type: number nullable: true description: 주당 액면가. total_value: type: number nullable: true description: 보유 자산의 총 가치입니다. percentage: type: number nullable: true description: 소수점 넷째 자리까지 표시된 정확한 지분율(%)입니다. required: - share_class - number_of_shares - currency - nominal_value - total_value - percentage KYBRegistryAddress: type: object description: >- 등기부에 기재된 주소로, 모든 국가 및 등기부 소스에 대해 동일한 형식입니다. 모든 키가 항상 존재하며, 등기부에서 공개하지 않는 부분은 null입니다. properties: type: type: string nullable: true description: >- 소문자로 표시된 주소 유형: 본점 소재지의 경우 `registered`, 기타 유형은 법인 등기부에 기재된 명칭(예: `postal`, `office`)을 따릅니다. 등기부에 주소 유형이 명시되지 않은 경우 `null`입니다. address: type: string description: 한 줄로 작성된 전체 주소입니다. 모든 주소에 항상 존재합니다. street: type: string nullable: true description: 도로명 및 번호. city: type: string nullable: true description: 시 또는 지역입니다. postal_code: type: string nullable: true description: 우편번호입니다. region: type: string nullable: true description: 지역, 주 또는 도입니다. country_code: type: string nullable: true description: ISO 3166-1 alpha-2 국가 코드입니다. description: type: string nullable: true description: 주소에 대해 등기소 자체에서 제공한 라벨(있는 경우)입니다. required: - type - address - street - city - postal_code - region - country_code - description KYBRegistryIndustry: type: object description: 등기부에서 기업을 분류한 업종 활동으로, 모든 국가 및 등기부 소스에 대해 동일한 형식입니다. properties: code: type: string nullable: true description: '등기부에 기재된 업종 코드입니다(예: `73110`).' description: type: string nullable: true description: 등기부에서 공개한 경우의 업종 라벨입니다. scheme: type: string nullable: true description: >- 분류 체계(보고한 출처와 관계없이 체계당 하나의 이름 사용): `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: type: boolean description: 기업의 주요 활동인 경우 true입니다. 목록이 비어 있지 않은 경우 정확히 하나의 항목이 주요 활동입니다. required: - code - description - scheme - is_primary KYBRegistryData: type: object nullable: true description: >- 기업에 대한 Didit의 정규화된 법인 등기부 세부 정보입니다: 소유 구조 결과(`ownership_error`, `section_errors`, `ubo_resolution`, `lite_enrichment`), update-data로 수정된 내용 및 자체 필드가 없는 등기부 사실 정보가 포함됩니다. 등기부 소스 자체의 원본 레코드는 절대 포함되지 않습니다. 모든 키는 선택 사항이며 기업에 해당 값이 있는 경우에만 표시됩니다. 새로운 키가 추가될 수 있습니다. 해당 필드가 다루는 내용에 대해서는 표준 필드(`addresses`, `industries`, `ownership`, `beneficial_owners[].shareholding`)를 확인하세요. properties: company_name: type: string description: Console에서 수정한 기업명입니다. registration_number: type: string description: 법인 등기부 또는 콘솔 수정사항에 명시된 등록번호입니다. country_code: type: string description: 등기부 또는 콘솔 수정 사항에 명시된 등록 국가입니다. region: type: string description: 등록 지역 또는 주입니다. incorporation_date: type: string description: 설립일(ISO 8601). registration_date: type: string description: 법인 등기부에서 설립일 외에 별도로 명시한 등록일(ISO 8601)입니다. dissolution_date: type: string description: 등기부에 기재된 경우의 해산일(ISO 8601)입니다. tax_number: type: string description: 납세자 번호입니다. vat_number: type: string description: VAT 번호입니다. legal_address: type: string description: 콘솔에서 수정된 법적 주소입니다. registered_address: type: string description: 등기부에 기재된 등록 주소입니다. company_type: type: string description: 법적 형태입니다. registry_status: type: string description: 법인 등기부상의 기업 상태입니다. verification_status: type: string description: 인증 상태입니다. alternative_names: type: string description: 기업이 거래에 사용하거나 사용했던 다른 상호입니다. nature_of_business: type: string description: 업종 설명입니다. registered_capital: type: string description: 인쇄된 자본금입니다. registered_capital_amount: type: string description: 십진수 문자열 형태의 자본금 금액입니다. registered_capital_currency: type: string description: 자본금 통화(ISO 4217)입니다. website: type: string description: 웹사이트입니다. email: type: string description: 연락처 이메일입니다. phone: type: string description: 연락처 전화번호입니다. legal_entity_identifier: type: string description: 법인식별기호(LEI). location_of_registration: type: string description: 등록지입니다. control_scheme: type: string description: 등기소에서 공개하는 경우 거버넌스 체계입니다. ownership_error: type: string enum: - 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 description: >- 요청된 소유 구조 등급이 제공되지 않은 이유로, `ownership.unavailable_reason`과 동일한 코드입니다. `no_owners_on_record`(등기소가 응답했으나 소유자를 명시하지 않음)와 `ownership_section_unavailable`(등기소에서 소유 구조 섹션을 반환하지 않음)은 서로 다른 결과입니다. section_errors: type: object description: >- 등기부에서 반환하지 않은 섹션으로, 섹션별(`officers`, `shareholders`, `group_structure`)로 키가 지정됩니다. 여기에 나열된 섹션은 전혀 전달되지 않았습니다. 그 옆에 빈 목록이 있더라도 해당 기업에 대해 아무것도 나타내지 않습니다. additionalProperties: $ref: '#/components/schemas/KYBRegistrySectionError' ubo_resolution: $ref: '#/components/schemas/KYBRegistryUboResolution' lite_enrichment: $ref: '#/components/schemas/KYBRegistryLiteEnrichment' registry_metadata: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: >- 등기소 명칭을 키로 하고 일반 값으로 표현된 해당 기업에 대한 등기소 자체 필드(레거시 레코드)입니다. 등기소 사실로 검토된 필드만 포함됩니다. registry_sources: type: array description: 기록을 읽어온 공식 등기부 목록입니다(레거시 기록). 다른 출처의 이름은 명시되지 않습니다. items: $ref: '#/components/schemas/KYBRegistrySource' previous_names: type: array items: type: string description: 해당 기업이 이전에 등록되었던 이름입니다(기존 기록). parent_companies: type: array items: type: string description: 등기부에 기재된 모회사 목록입니다(레거시 기록). documents_available: type: integer description: 등기부에서 해당 기업에 대해 제공하는 제출 서류 수(레거시 기록)입니다. KYBRegistryOwnership: type: object description: 모든 국가 및 등기부 출처에 대해 동일한 형식으로 제공되는 소유 구조(주주 / UBO) 등급의 결과입니다. properties: status: type: string nullable: true enum: - not_requested - pending - delivered - not_held - unavailable - null description: >- 등기소가 소유 구조를 공개한 경우 `delivered`, 소유 구조 등기소가 응답했으나 기업이 전혀 등재되어 있지 않은 경우 `not_held`(`unavailable_reason` 참조), 그 외의 사유로 소유 구조 데이터를 제공하지 않은 경우 `unavailable`(`unavailable_reason` 참조), 등기소에서 아직 조회 중인 경우 `pending`, Basic 등급인 경우 `not_requested`. tier_requested: type: string nullable: true enum: - basic - shareholders - ubo - null description: 워크플로가 주문한 등급입니다. tier_delivered: type: string nullable: true enum: - basic - shareholders - ubo - null description: >- 등기부에서 제공한(그리고 결제 청구되는) 등급입니다. 직접 주주만으로 응답된 UBO 요청은 `shareholders`가 됩니다. unavailable_reason: type: string nullable: true enum: - 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 description: >- 요청된 소유 구조 등급이 제공되지 않은 이유입니다. `status`가 `unavailable` 또는 `pending`이 아닌 경우 null입니다. direct_ownership_complete: type: boolean nullable: true description: >- 직접 주주의 명시된 지분 합계가 100%인 경우(반올림 오차 1퍼센트포인트 이내) true, 그렇지 않은 경우 false, 소유 구조가 전송되지 않았거나 지분이 명시되지 않은 경우 null입니다. unresolved: type: array description: '법인 등기부에서 확인할 수 없는 소유 구조 체인의 일부(예: 직접 소유자 상위의 그룹 구조가 기록에 없음)입니다.' items: type: object properties: reason: type: string section: type: string nullable: true required: - status - tier_requested - tier_delivered - unavailable_reason - direct_ownership_complete - unresolved KYBRegistrySectionError: type: object description: 법인 등기부에서 반환하지 않은 섹션입니다. properties: status_code: type: integer nullable: true description: 해당 섹션에 대해 등기소에서 응답한 상태입니다. required: - status_code KYBRegistryUboResolution: type: object description: UBO 등급이 기업의 상위 소유 구조 체인을 탐색한 방식입니다. properties: parent_chain: type: array description: 최상위 모회사부터 해당 기업까지의 기업 모회사 목록입니다. items: $ref: '#/components/schemas/KYBRegistryGroupCompany' subsidiaries: type: array description: 기업 집단 내에서 해당 기업 바로 아래에 위치한 기업 목록입니다. items: $ref: '#/components/schemas/KYBRegistryGroupCompany' unresolved: type: array description: 법인 등기부에서 확인할 수 없는 소유 구조 체인의 일부입니다(`ownership.unresolved`와 동일한 항목). items: type: object properties: reason: type: string description: >- 이유(예: `no_group_structure_on_record`, `selected_company_not_in_group_structure` 또는 `section_error`)입니다. section: type: string nullable: true description: '해당 섹션입니다(예: `group_structure`).' required: - reason - section required: - parent_chain - subsidiaries - unresolved KYBRegistryLiteEnrichment: type: object description: 해당 국가의 다른 등기부 출처가 채운 Lite 프로필의 빈 필드입니다. 출처는 명시되지 않습니다. properties: fields: type: array items: type: string description: 입력된 기업 필드입니다. people_added: type: integer description: 추가된 임원 또는 소유자 수입니다. required: - fields - people_added KYBRegistrySource: type: object description: 기록을 읽어온 공식 등기소입니다. 공식 정부 등기소, 규제 기관 및 공식 식별자 시스템만 명시되며, 기타 소스는 제외됩니다. properties: name: type: string description: '등록부 명칭(예: `UK Companies House`).' source_type: type: string enum: - official description: 항상 `official`입니다. required: - name - source_type KYBRegistryGroupCompany: type: object description: 법인 등기부상 신원에 따른 기업 그룹의 계열사입니다. properties: name: type: string nullable: true description: 기업명입니다. country_code: type: string nullable: true description: 등록 국가. registration_number: type: string nullable: true description: 등록번호입니다. required: - name - country_code - registration_number securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.