> ## 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) 세션의 주요 인물 목록에 개인 또는 기업을 아직 선언하지 않은 상태로 추가합니다. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/session/{sessionId}/kyb/parties/drafts/ 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/drafts/: post: tags: - Sessions summary: KYB 당사자 초안 생성 description: >- 이 KYB 세션을 위해 준비 중인 목록에 당사자(개인 또는 법인)를 추가합니다. 호스팅된 주요 인물 화면과 동일한 필드 및 규칙이 적용됩니다. 개인의 경우 `full_name` 또는 `first_name` 및 `last_name`, 최소 하나의 역할, 국적이 필요합니다. 법인의 경우 `company_name` 및 설립 국가를 `nationality`에 입력해야 합니다. `POST /v3/session/{sessionId}/kyb/parties/submit/` 호출 전까지는 신고되거나 청구되지 않습니다. `write:businesses` 권한이 필요합니다. operationId: post_v3_session_kyb_party_drafts 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: true content: application/json: schema: type: object required: - entity_type - nationality properties: entity_type: type: string enum: - person - company description: 해당 당사자가 개인인지 기업인지 여부입니다. full_name: type: string maxLength: 255 description: 개인의 성명입니다. 이 값을 전송하거나, `first_name` 및 `last_name`을 전송하십시오. first_name: type: string maxLength: 128 last_name: type: string maxLength: 128 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: 해당 당사자가 보유한 역할. `roles`와 서로 바꿔 사용할 수 있으며, 둘 다 전송되면 병합됩니다. roles: type: array items: 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: 해당 주체가 보유한 모든 역할입니다. 개인은 최소 하나의 역할(여기 또는 `role`)이 필요합니다. position: type: string maxLength: 128 description: 개인의 직책입니다. date_of_birth: type: string format: date nullable: true company_name: type: string maxLength: 255 description: 기업 당사자의 이름입니다. `entity_type`이 `company`인 경우 필수입니다. registration_number: type: string maxLength: 100 description: 기업 당사자의 등록번호입니다. email: type: string format: email description: >- 인증 링크가 전송되는 위치입니다. 당사자가 인증을 완료해야 할 때 필수이며, 이는 워크플로의 역할 설정 및 소유 구조 임계값에 따라 결정됩니다. ownership_percent: type: number nullable: true description: 해당 주체가 보유한 기업의 지분입니다. nationality: type: string maxLength: 100 description: 개인의 국적 또는 기업의 설립 국가입니다. 모든 당사자에게 필수입니다. phone_number: type: string maxLength: 32 custom_fields: type: object additionalProperties: true description: 워크플로에서 정의된 추가 필드입니다. skip_verification: type: boolean default: false description: >- 이 당사자의 인증 건너뛰기를 요청합니다. 워크플로의 주요 인물 설정에서 해당 당사자의 역할에 건너뛰기가 허용된 경우에만 적용됩니다. example: entity_type: person first_name: Ana last_name: Lopez roles: - ubo - director ownership_percent: 60 nationality: MEX email: ana.lopez@example.com date_of_birth: '1984-06-12' responses: '201': description: 초안이 생성되었습니다. content: application/json: schema: type: object required: - draft_id - created_at - updated_at - party properties: draft_id: type: string format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time party: type: object required: - entity_type - nationality properties: entity_type: type: string enum: - person - company description: 해당 당사자가 개인인지 기업인지 여부입니다. full_name: type: string maxLength: 255 description: >- 개인의 성명입니다. 이 값을 전송하거나, `first_name` 및 `last_name`을 전송하십시오. first_name: type: string maxLength: 128 last_name: type: string maxLength: 128 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: >- 해당 당사자가 보유한 역할. `roles`와 서로 바꿔 사용할 수 있으며, 둘 다 전송되면 병합됩니다. roles: type: array items: 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: >- 해당 주체가 보유한 모든 역할입니다. 개인은 최소 하나의 역할(여기 또는 `role`)이 필요합니다. position: type: string maxLength: 128 description: 개인의 직책입니다. date_of_birth: type: string format: date nullable: true company_name: type: string maxLength: 255 description: 기업 당사자의 이름입니다. `entity_type`이 `company`인 경우 필수입니다. registration_number: type: string maxLength: 100 description: 기업 당사자의 등록번호입니다. email: type: string format: email description: >- 인증 링크가 전송되는 위치입니다. 당사자가 인증을 완료해야 할 때 필수이며, 이는 워크플로의 역할 설정 및 소유 구조 임계값에 따라 결정됩니다. ownership_percent: type: number nullable: true description: 해당 주체가 보유한 기업의 지분입니다. nationality: type: string maxLength: 100 description: 개인의 국적 또는 기업의 설립 국가입니다. 모든 당사자에게 필수입니다. phone_number: type: string maxLength: 32 custom_fields: type: object additionalProperties: true description: 워크플로에서 정의된 추가 필드입니다. skip_verification: type: boolean default: false description: >- 이 당사자의 인증 건너뛰기를 요청합니다. 워크플로의 주요 인물 설정에서 해당 당사자의 역할에 건너뛰기가 허용된 경우에만 적용됩니다. example: draft_id: 5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d created_at: '2026-10-31T10:00:00Z' updated_at: '2026-10-31T10:00:00Z' party: entity_type: person first_name: Ana last_name: Lopez roles: - ubo - director ownership_percent: 60 nationality: MEX email: ana.lopez@example.com date_of_birth: '1984-06-12' '400': description: 당사자 필드가 유효하지 않거나 필수 필드가 누락되었습니다. content: application/json: schema: type: object properties: detail: type: string description: 사람이 읽기 쉬운 오류 메시지입니다. example: non_field_errors: - Person parties require at least one role. '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. '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_session_not_writable`). content: application/json: schema: type: object properties: detail: type: string description: 사람이 읽기 쉬운 오류 메시지입니다. code: type: string example: detail: This verification session is no longer accepting changes. code: kyb_session_not_writable '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.create_kyb_party_draft( "33333333-4444-5555-6666-777777777777", entity_type="person", first_name="Ana", last_name="Lopez", roles=["ubo", "director"], date_of_birth="1984-06-12", email="ana.lopez@example.com", ownership_percent=60.0, nationality="MEX", ) 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.createKybPartyDraft("33333333-4444-5555-6666-777777777777", { entity_type: "person", first_name: "Ana", last_name: "Lopez", roles: ["ubo", "director"], date_of_birth: "1984-06-12", email: "ana.lopez@example.com", ownership_percent: 60.0, nationality: "MEX", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.CreateKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsCreateKYBPartyDraftParams{\n\tEntityType: \"person\",\n\tFirstName: didit.String(\"Ana\"),\n\tLastName: didit.String(\"Lopez\"),\n\tRoles: didit.Some([]didit.SessionsCreateKYBPartyDraftParamsRoles{\"ubo\", \"director\"}),\n\tDateOfBirth: didit.String(\"1984-06-12\"),\n\tEmail: didit.String(\"ana.lopez@example.com\"),\n\tOwnershipPercent: didit.Float(60.0),\n\tNationality: \"MEX\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.time.LocalDate; import java.util.List; import me.didit.Didit; import me.didit.types.SessionsCreateKybPartyDraftParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().createKybPartyDraft("33333333-4444-5555-6666-777777777777", SessionsCreateKybPartyDraftParams.builder() .entityType(SessionsCreateKybPartyDraftParams.EntityType.of("person")) .firstName("Ana") .lastName("Lopez") .roles(List.of(SessionsCreateKybPartyDraftParams.Roles.of("ubo"), SessionsCreateKybPartyDraftParams.Roles.of("director"))) .dateOfBirth(LocalDate.parse("1984-06-12")) .email("ana.lopez@example.com") .ownershipPercent(60.0) .nationality("MEX") .build()); System.out.println(result); - lang: php label: PHP source: >- sessions->createKybPartyDraft('33333333-4444-5555-6666-777777777777', [ 'entity_type' => 'person', 'first_name' => 'Ana', 'last_name' => 'Lopez', 'roles' => ['ubo', 'director'], 'date_of_birth' => '1984-06-12', 'email' => 'ana.lopez@example.com', 'ownership_percent' => 60.0, 'nationality' => 'MEX', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.create_kyb_party_draft( "33333333-4444-5555-6666-777777777777", entity_type: "person", first_name: "Ana", last_name: "Lopez", roles: ["ubo", "director"], date_of_birth: "1984-06-12", email: "ana.lopez@example.com", ownership_percent: 60.0, nationality: "MEX" ) 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.CreateKybPartyDraftAsync("33333333-4444-5555-6666-777777777777", new SessionsCreateKybPartyDraftParams { EntityType = "person", FirstName = "Ana", LastName = "Lopez", Roles = new SessionsCreateKybPartyDraftParamsRoles[] { "ubo", "director" }, DateOfBirth = "1984-06-12", Email = "ana.lopez@example.com", OwnershipPercent = 60.0, Nationality = "MEX", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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.