> ## 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 주요 인물 제출 API

> Didit의 KYB 세션에서 준비된 주요 인물을 등록하고, 인증이 필요한 각 당사자의 KYC 인증을 시작합니다.



## OpenAPI

````yaml ko/openapi-25.json POST /v3/session/{sessionId}/kyb/parties/submit/
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/session/{sessionId}/kyb/parties/submit/:
    post:
      tags:
        - Sessions
      summary: KYB 당사자 초안 제출
      description: >-
        저장된 초안을 회사의 주요 인물로 신고합니다. 이는 귀하의 API 키로 실행되는 호스팅 주요 인물 단계입니다. Didit은
        워크플로의 역할 설정 및 소유권 임계값에 따라 검증해야 할 대상을 결정하고, 각 대상에 대해 개별 KYC 세션(법인 소유자의 경우
        KYB 하위 세션)을 하나씩 생성하며, 워크플로에서 요구하는 이메일을 발송하고 세션을 진행합니다. 각 하위 세션은 호스팅 플로우와
        동일하게 과금됩니다. 초안은 소진됩니다. 성공적으로 제출한 후 호출을 반복해도 변경되지 않으며 `already_submitted:
        true` 및 이미 존재하는 대상 목록과 함께 `200`을 반환합니다. 세션은 주요 인물 단계에 있어야 합니다. 각 사람에게
        `kyc_session_url`을 전송하거나 임베드하세요. `write:businesses` 권한이 필요합니다.
      operationId: post_v3_session_kyb_parties_submit
      parameters:
        - name: sessionId
          in: path
          required: true
          description: 기업 확인(KYB) 세션의 UUID입니다. 해당 API 키의 애플리케이션에 속해 있어야 합니다.
          schema:
            type: string
            format: uuid
            example: 33333333-4444-5555-6666-777777777777
        - name: node_id
          in: query
          required: false
          description: >-
            KYB 단계의 워크플로 노드입니다. 워크플로에 둘 이상의 KYB 노드가 있는 경우에만 필요하며, 기본적으로 Didit은
            세션 자체의 노드를 사용합니다.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  maxLength: 10
                  description: 세션이 진행되는 다음 단계의 응답을 번역하는 데 사용되는 로캘입니다.
            example:
              locale: es
      responses:
        '200':
          description: 신고된(또는 이미 신고된) 당사자입니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  next_step:
                    type: string
                    nullable: true
                    description: 세션이 위치한 단계입니다.
                  status:
                    type: string
                    description: 기업 세션의 상태입니다.
                  advanced:
                    type: boolean
                    description: 이 호출로 당사자가 선언되고 세션이 진행된 경우 `true`입니다.
                  already_submitted:
                    type: boolean
                    description: 이전 호출을 통해 당사자들이 이미 선언된 경우 `true`입니다.
                  kyb_key_people_status:
                    type: string
                  parties:
                    type: array
                    items:
                      $ref: '#/components/schemas/KYBKeyPeopleParty'
              example:
                valid: true
                next_step: FINISHED
                status: In Progress
                advanced: true
                already_submitted: false
                kyb_key_people_status: In Progress
                parties: []
        '401':
          description: >-
            스코프가 지정된 API 키가 만료되었습니다. `401`이 반환되는 유일한 경우이며, 누락되었거나 유효하지 않거나 폐기된
            키에는 `403`이 반환됩니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              examples:
                Expired key:
                  summary: 키의 만료일이 지났습니다
                  value:
                    detail: This API key has expired.
        '402':
          description: 하위 인증 세션에 사용할 조직의 크레딧이 남아 있지 않습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              example:
                detail: Insufficient credits.
        '403':
          description: >-
            인증 또는 권한 부여에 실패했습니다. 키가 누락된 경우 `403`이 반환되며, 다른 애플리케이션의 키, 이
            endpoint에 필요한 권한이 없는 범위 지정 키, 키의 IP 허용 목록 외부에서 보낸 요청의 경우에도 마찬가지입니다.
            잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. `detail`로 구분하십시오.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              examples:
                Missing or invalid credentials:
                  summary: x-api-key 헤더가 없거나 키 검증에 실패했습니다
                  value:
                    detail: >-
                      Authentication credentials were not provided or are
                      invalid.
                Other application:
                  summary: 세션과 다른 애플리케이션에 속한 유효한 키입니다
                  value:
                    detail: You do not have permission to perform this action.
                Scoped key without decisions write:
                  summary: '스코프 지정 키에 decisions: write 권한이 없음'
                  value:
                    detail: This API key has no write access to decisions.
                IP not allowed:
                  summary: 키의 IP 허용 목록 외부로부터의 요청
                  value:
                    detail: This API key can't be used from this IP address.
        '404':
          description: >-
            세션이 존재하지 않거나, 삭제되었거나, 다른 애플리케이션에 속해 있거나, 범위가 지정된 키의 제한 범위를 벗어났습니다.
            이를 구분하는 세부 정보는 제공되지 않습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              example:
                detail: Session not found.
        '409':
          description: >-
            `kyb_no_party_drafts`: 제출할 내용이 없습니다.
            `kyb_parties_already_submitted`: 당사자가 선언된 후 임시 초안이 추가되었습니다.
            `kyb_step_mismatch`: 세션이 주요 인물 단계에 있지 않습니다(`next_step`에 해당 단계 이름이
            지정됨). `kyb_session_not_writable`: 세션이 완료되었습니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
                  code:
                    type: string
                  next_step:
                    type: string
              example:
                detail: There are no draft parties to submit.
                code: kyb_no_party_drafts
        '429':
          description: >-
            속도 제한을 초과했습니다. API 키당 분당 300회의 쓰기(POST, PATCH, DELETE) 요청으로 제한됩니다.
            재시도하기 전에 `Retry-After`초 동안 대기하세요. `X-RateLimit-*` 헤더에 한도 정보가 표시됩니다.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: 사람이 읽기 쉬운 오류 메시지입니다.
              examples:
                Rate limited:
                  summary: 현재 분에 할당된 예산이 소진되었습니다
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
          headers:
            Retry-After:
              description: 재시도하기 전 대기할 시간(초)입니다.
              schema:
                type: integer
                minimum: 1
                example: 30
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.sessions.submit_kyb_parties(
                "33333333-4444-5555-6666-777777777777",
                locale="es",
            )
            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.sessions.submitKybParties("33333333-4444-5555-6666-777777777777",
            {
              locale: "es",
            });

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.SubmitKYBParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsSubmitKYBPartiesParams{\n\tLocale: didit.String(\"es\"),\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.SessionsSubmitKybPartiesParams;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.sessions().submitKybParties("33333333-4444-5555-6666-777777777777",
            SessionsSubmitKybPartiesParams.builder()
                    .locale("es")
                    .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->sessions->submitKybParties('33333333-4444-5555-6666-777777777777',
            [
                'locale' => 'es',
            ]);

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.sessions.submit_kyb_parties(
              "33333333-4444-5555-6666-777777777777",
              locale: "es"
            )
            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.Sessions.SubmitKybPartiesAsync("33333333-4444-5555-6666-777777777777",
            new SessionsSubmitKybPartiesParams

            {
                Locale = "es",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    KYBKeyPeopleParty:
      type: object
      description: >-
        하위 인증을 포함하는 기업 확인(KYB) 세션의 주요 인물 당사자입니다. 동일한 당사자가 기업 세션 결정의
        `key_people_checks[].submitted.parties[]`에 나타납니다.
      required:
        - uuid
        - entity_type
        - source
        - name
        - is_active
        - is_skipped
        - requires_verification
        - roles
        - kyc_session_deleted
        - kyb_sub_session_deleted
      properties:
        uuid:
          type: string
          format: uuid
          description: 당사자 식별자입니다.
        entity_type:
          type: string
          enum:
            - person
            - company
          description: 해당 당사자가 개인인지 기업인지 여부입니다.
        source:
          type: string
          enum:
            - REGISTRY
            - USER
          description: '`REGISTRY`: 법인 등기부에서 가져옴. `USER`: 주요 인물 화면에서 입력함.'
        name:
          type: string
          description: 당사자의 표시 이름입니다.
        first_name:
          type: string
          nullable: true
          description: 이름(개인).
        last_name:
          type: string
          nullable: true
          description: 성(개인).
        company_name:
          type: string
          nullable: true
          description: 기업명(기업 당사자).
        registration_number:
          type: string
          nullable: true
          description: 기업 등록번호(기업 당사자).
        email:
          type: string
          format: email
          nullable: true
          description: 인증 링크가 전송되는 이메일입니다.
        nationality:
          type: string
          nullable: true
          description: 개인의 경우 국적, 기업의 경우 법인 설립 국가입니다.
        phone_number:
          type: string
          nullable: true
          description: 해당 주체에 대해 수집된 전화번호입니다.
        date_of_birth:
          type: string
          format: date
          nullable: true
          description: 생년월일(개인)입니다.
        position:
          type: string
          nullable: true
          description: 자유 형식 직함입니다(개인).
        custom_fields:
          type: object
          additionalProperties: true
          description: 당사자에 대해 수집된 워크플로 정의 커스텀 필드이며, 필드 키를 키로 사용합니다.
        is_active:
          type: boolean
          description: 해당 당사자가 활성 상태인지 여부입니다.
        is_skipped:
          type: boolean
          description: 해당 당사자가 인증 면제 대상인지 여부입니다. 재생성하면 초기화됩니다.
        requires_verification:
          type: boolean
          description: 역할 및 소유 구조 규칙에 따라 이 당사자에 대한 인증이 필요한지 여부입니다.
        roles:
          type: array
          description: 해당 당사자가 회사에서 보유한 역할.
          items:
            type: object
            required:
              - role
              - ownership_percent
              - voting_percent
            properties:
              role:
                type: string
                enum:
                  - director
                  - non_executive_director
                  - secretary
                  - chairman
                  - ubo
                  - shareholder
                  - representative
                  - founder
                  - legal_advisor
                  - authorized_signatory
                  - trustee
                  - beneficiary
                  - settlor
                  - protector
                  - company_officer
                  - investor
                  - other
                description: 역할 코드.
              ownership_percent:
                type: number
                nullable: true
                description: 알려진 경우, 이 역할의 소유 비율입니다.
              voting_percent:
                type: number
                nullable: true
                description: 알려진 경우 이 역할에 대한 의결권 비율입니다.
        kyc_session_id:
          type: string
          format: uuid
          nullable: true
          description: 하위 개인 KYC 세션(개인)입니다.
        kyc_session_status:
          type: string
          nullable: true
          enum:
            - Not Started
            - In Progress
            - Approved
            - Declined
            - In Review
            - Expired
            - Abandoned
            - Kyc Expired
            - Resubmitted
            - Awaiting User
            - null
          description: 하위 KYC 세션의 상태입니다. 삭제된 세션은 삭제 당시의 상태를 유지합니다.
        kyc_session_url:
          type: string
          format: uri
          nullable: true
          description: >-
            하위 KYC 세션의 호스팅 링크입니다. 세션이 없거나 삭제된 경우, 그리고 `sessions: write` 권한이 없는
            범위 지정 API 키의 경우 `null`입니다.
        kyc_session_deleted:
          type: boolean
          description: 하위 KYC 세션이 삭제되어 완료될 수 없습니다.
        kyb_sub_session_id:
          type: string
          format: uuid
          nullable: true
          description: 하위 KYB 세션(법인 당사자)입니다.
        kyb_sub_session_status:
          type: string
          nullable: true
          enum:
            - Not Started
            - In Progress
            - Approved
            - Declined
            - In Review
            - Expired
            - Abandoned
            - Kyc Expired
            - Resubmitted
            - Awaiting User
            - null
          description: 하위 KYB 세션의 상태입니다.
        kyb_sub_session_url:
          type: string
          format: uri
          nullable: true
          description: 하위 KYB 세션의 호스팅 링크이며, `kyc_session_url`과 동일한 `null` 규칙이 적용됩니다.
        kyb_sub_session_deleted:
          type: boolean
          description: '`kyc_session_deleted`에 대응하는 기업 당사자 이벤트입니다.'
        verification_workflow_type:
          type: string
          nullable: true
          enum:
            - kyc
            - kyb
            - adaptive_age_verification
            - biometric_authentication
            - address_verification
            - questionnaire_verification
            - email_verification
            - phone_verification
            - null
          description: 하위 세션이 실행하는 워크플로 유형입니다.
        verification_workflow_id:
          type: string
          format: uuid
          nullable: true
          description: 하위 세션이 실행하는 워크플로입니다.
        verification_workflow_label:
          type: string
          nullable: true
          description: 해당 워크플로의 라벨입니다.
        verification_workflow_features:
          type: array
          nullable: true
          description: 현재 상태가 포함된 하위 세션 워크플로의 기능입니다.
          items:
            type: object
            required:
              - feature
              - status
            properties:
              feature:
                type: string
                description: '기능 코드(예: `ID_VERIFICATION` 또는 `LIVENESS`).'
              status:
                type: string
                description: 실행될 때까지 `Not Finished`인 기능 상태입니다.
        didit_internal_id:
          type: string
          format: uuid
          nullable: true
          description: 인증된 인물이 확인된 경우 해당 인물에 대한 Didit의 식별자입니다.
  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.