> ## 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.

# 기업 생성 API: 벤더 KYB 엔티티

> KYB 세션 실행 전에 Didit 기업(KYB) 엔티티를 미리 등록합니다. 외부 데이터베이스에서 일괄 온보딩하거나 거래 모니터링용으로 등록하세요.



기업 생성 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<pre>

\`Goal: Pre-create a Didit Business (KYB) entity by vendor_data before any KYB session runs.

Endpoint: POST https://verification.didit.me/v3/businesses/create/
Auth header: x-api-key: <DIDIT_API_KEY>
Content-Type: application/json

Request body fields:
\- vendor_data (string, REQUIRED) — your unique identifier. Free-form string, NOT a UUID. Must be unique among non-deleted businesses for the app. Normalised lowercase + whitespace trim ("COMPANY-1" and "company-1" collide).
\- display_name (string, nullable) — friendly display name shown in Console (takes precedence over legal_name).
\- legal_name (string, nullable)
\- registration_number (string, nullable)
\- country_code (string, nullable) — country of incorporation, ISO 3166-1 alpha-2 (e.g. "GB", "US").
\- region (string, nullable) — ISO 3166-2 subdivision code.
\- status (enum) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorBusinessStatusChoices). Defaults to "ACTIVE".
\- metadata (object, nullable) — arbitrary JSON.

curl:
curl -X POST 'https://verification.didit.me/v3/businesses/create/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US"}'

Response 201: full BusinessDetailItem (same shape as GET /v3/businesses/{vendor_data}/). Includes didit_internal_id (UUID), session_count=0, metadata, comments=[], created_at, updated_at. See /reference/data-models.

Failure modes (envelope {"detail": "..."} for auth):
\- 400 — validation errors keyed by field. Common cases:
\{ "vendor_data": ["A business with this vendor_data already exists."] }  // NOT idempotent — use PATCH /v3/businesses/{vendor_data}/ to update.
\{ "vendor_data": ["This field is required."] }
\{ "metadata": ["Metadata must be a JSON object."] }
\- 401 — missing/invalid x-api-key.
\- 403 — lacks create:businesses.
\- 429 — rate-limited.

Upsert pattern (NOT idempotent on vendor_data):
GET /v3/businesses/{vendor_data}/  → on 404, POST /v3/businesses/create/; on 200, PATCH /v3/businesses/{vendor_data}/.

Notes:
\- Registry-derived fields (legal_name, registration_number, country_code) can be seeded here but will be OVERWRITTEN by the first approved Business Verification (KYB) session's registry data.
\- last_activity_at is set at the moment of creation.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

붙여넣을 곳

## 개요기업 확인(KYB) 세션이 실행되기 전에 [기업 엔터티](https://docs.didit.me/ko/entities/businesses/overview.md)를 명시적으로 생성합니다.## 사용 시점- 첫 번째 기업 확인(KYB) 세션 전에 **메타데이터**(파트너, 등급, 내부 식별자)를 미리 입력합니다.
- 기존 기업 목록을 가진 다른 KYB 공급업체에서 **마이그레이션**합니다.
- **거래 전용 등록**: 오프라인 절차로 검증된 기업의 거래를 제출합니다.## 참고 사항- `vendor_data`는 필수이며 애플리케이션마다 고유해야 합니다. 중복되면 충돌 오류가 반환됩니다. 업데이트하려면 [`PATCH /v3/businesses/{vendor_data}/`](https://docs.didit.me/ko/management-api/businesses/update)를 사용하십시오.
- 등기부에서 가져오는 필드(`legal_name`, `registration_number`, `country_code`)는 미리 입력할 수 있지만, 첫 번째로 승인된 기업 확인(KYB) 세션의 등기부 데이터로 **덮어쓰여집니다**.
- `country_code`가 애플리케이션의 [위험 국가](https://docs.didit.me/ko/entities/businesses/blocklist.md#위험-국가) 목록과 일치하면 기업은 `BLOCKED` 상태로 생성됩니다.
- `business.data.updated` 이벤트를 발생시킵니다.## 권한역할에 `create:businesses` 권한이 있어야 합니다.## 관련 항목- [기업 데이터 모델](https://docs.didit.me/ko/entities/businesses/data-model.md)
- [공급업체 데이터 연결](https://docs.didit.me/ko/entities/vendor-data-linking.md)
- [기업 운영](https://docs.didit.me/ko/entities/businesses/operations.md)


## OpenAPI

````yaml ko/openapi-25.json POST /v3/businesses/create/
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/businesses/create/:
    post:
      tags:
        - Businesses
      summary: 기업 생성
      description: >-
        KYB 세션 *없이* [기업](/entities/businesses)을 사전 생성합니다. 모든 필드는 선택 사항이지만,
        `vendor_data`는 항상 전송해야 합니다. 이 값이 없으면 해당 레코드를 세션이나 거래에 연결할 수 없습니다. 제공 시
        `vendor_data`는 삭제되지 않은 기업 간에 고유해야 합니다(정확히 일치해야 하며, 충돌 시 400 반환). 멱등성이
        적용되지 않습니다.
      operationId: create_business
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vendor_data:
                  type: string
                  nullable: true
                  description: >-
                    귀하가 지정한 해당 기업의 고유 식별자입니다(자유 형식 문자열, UUID 아님). 선택 사항이지만 적극
                    권장됩니다. 제공되는 경우 해당 애플리케이션의 삭제되지 않은 기업 간에 고유해야 하며, 전송된 값과 정확히
                    일치해야 합니다.
                display_name:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: 콘솔에 표시되는 친숙한 표시 이름입니다(UI 표시 시 `legal_name`보다 우선 적용됨).
                legal_name:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: 기업의 공식 법인명입니다.
                registration_number:
                  type: string
                  nullable: true
                  maxLength: 100
                  description: 기업 등록번호 또는 법인 설립 번호입니다.
                country_code:
                  type: string
                  nullable: true
                  maxLength: 10
                  description: '설립 국가(ISO 3166-1 alpha-2, 예: `GB`, `US`).'
                status:
                  type: string
                  enum:
                    - ACTIVE
                    - FLAGGED
                    - BLOCKED
                  default: ACTIVE
                  description: 초기 라이프사이클 상태입니다. 기본값은 `ACTIVE`입니다.
                metadata:
                  type: object
                  nullable: true
                  description: 기업에 연결하는 임의의 JSON 객체입니다. 기본값은 `{}`입니다.
            examples:
              Basic:
                summary: 권장 최소값
                value:
                  vendor_data: company-456
                  legal_name: New Corp Ltd
                  country_code: US
              Full:
                summary: 모든 필드
                value:
                  vendor_data: company-789
                  display_name: New Corp
                  legal_name: New Corp International Ltd
                  registration_number: '98765432'
                  country_code: DE
                  status: ACTIVE
                  metadata:
                    industry: fintech
                    tier: enterprise
      responses:
        '201':
          description: 기업이 생성되었습니다. 전체 기업 레코드가 반환됩니다(기업 조회와 동일한 형식).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessDetailItem'
              examples:
                Created:
                  value:
                    didit_internal_id: a1b2c3d4-e5f6-4890-abcd-ef1234567890
                    vendor_data: company-456
                    display_name: null
                    legal_name: New Corp Ltd
                    registration_number: null
                    country_code: US
                    effective_name: New Corp Ltd
                    status: ACTIVE
                    session_count: 0
                    approved_count: 0
                    declined_count: 0
                    in_review_count: 0
                    features: {}
                    features_list: []
                    last_session_at: null
                    last_activity_at: '2026-03-15T10:30:00Z'
                    first_session_at: null
                    tags: []
                    created_at: '2026-03-15T10:30:00Z'
                    metadata: {}
                    updated_at: '2026-03-15T10:30:00Z'
        '400':
          description: >-
            유효하지 않은 본문 — 일반적으로 중복된 `vendor_data`, 알 수 없는 `status`, 또는 잘못된 형식의
            `metadata`입니다.
          content:
            application/json:
              examples:
                Duplicate:
                  value:
                    vendor_data:
                      - A business with this vendor_data already exists.
                Bad status:
                  value:
                    status:
                      - >-
                        Invalid status. Valid options are: ACTIVE, FLAGGED,
                        BLOCKED
                Bad metadata:
                  value:
                    metadata:
                      - Metadata must be a JSON object.
        '403':
          description: >-
            API 키가 누락되었거나 유효하지 않거나 취소되었습니다. 또는 키가 이 애플리케이션에 대한 기업을 생성할 수 없습니다.
            키가 누락되면 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: 속도 제한 초과. 대기 후 `Retry-After`에 지정된 시간 간격이 지난 뒤 재시도하세요.
          content:
            application/json:
              examples:
                Rate limited:
                  value:
                    detail: Request was throttled. Expected available in 30 seconds.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST 'https://verification.didit.me/v3/businesses/create/' \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{"vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US"}'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.businesses.create(
                vendor_data="company-456",
                legal_name="New Corp Ltd",
                country_code="US",
            )
            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.businesses.create({
              vendor_data: "company-456",
              legal_name: "New Corp Ltd",
              country_code: "US",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Create(ctx, didit.BusinessesCreateParams{\n\tVendorData:  didit.String(\"company-456\"),\n\tLegalName:   didit.String(\"New Corp Ltd\"),\n\tCountryCode: didit.String(\"US\"),\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.BusinessesCreateParams;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.businesses().create(BusinessesCreateParams.builder()
                    .vendorData("company-456")
                    .legalName("New Corp Ltd")
                    .countryCode("US")
                    .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->businesses->create([
                'vendor_data' => 'company-456',
                'legal_name' => 'New Corp Ltd',
                'country_code' => 'US',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

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

            result = didit.businesses.create(
              vendor_data: "company-456",
              legal_name: "New Corp Ltd",
              country_code: "US"
            )
            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.Businesses.CreateAsync(new
            BusinessesCreateParams

            {
                VendorData = "company-456",
                LegalName = "New Corp Ltd",
                CountryCode = "US",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    BusinessDetailItem:
      type: object
      description: 전체 기업 상세 정보입니다. 메타데이터 및 updated_at으로 BusinessListItem을 확장합니다.
      allOf:
        - $ref: '#/components/schemas/BusinessListItem'
        - type: object
          properties:
            metadata:
              type: object
              description: 이 기업에 첨부한 커스텀 메타데이터 JSON입니다. 기본값은 `{}`입니다.
            updated_at:
              type: string
              format: date-time
    BusinessListItem:
      type: object
      description: 인증된 기업입니다.
      properties:
        didit_internal_id:
          type: string
          format: uuid
          description: 이 기업에 대한 Didit의 고유 내부 UUID입니다.
        vendor_data:
          type: string
          nullable: true
          description: >-
            귀하가 지정한 해당 기업의 고유 식별자입니다(세션 생성 시 전달됨). 벤더 식별자가 제공되지 않은 경우 null일 수
            있습니다.
        display_name:
          type: string
          nullable: true
          description: 직접 설정한 커스텀 표시 이름
        legal_name:
          type: string
          nullable: true
          description: 등기부 또는 직접 입력에서 가져온 공식 법인명
        registration_number:
          type: string
          nullable: true
          description: 기업 등록번호 또는 법인 설립 번호
        country_code:
          type: string
          nullable: true
          description: '설립 국가(ISO 3166-1 alpha-2, 예: `GB`, `US`).'
        effective_name:
          type: string
          nullable: true
          description: '사용 가능한 최적의 이름: display_name이 설정된 경우 해당 값, 그렇지 않으면 legal_name'
        status:
          type: string
          enum:
            - ACTIVE
            - FLAGGED
            - BLOCKED
          description: >-
            기업 레코드의 수명 주기 상태입니다(세션 상태가 아님). 기본값은 `ACTIVE`이며, `FLAGGED`는 수동 확인
            필요로 표시하고, `BLOCKED`는 해당 `vendor_data`에 대한 새 세션을 방지합니다.
        session_count:
          type: integer
          description: 해당 기업의 총 인증 세션 수
        approved_count:
          type: integer
          description: 승인된 세션 수
        declined_count:
          type: integer
          description: 거부된 세션 수
        in_review_count:
          type: integer
          description: 검토 중인 세션 수
        features:
          type: object
          description: >-
            이 기업의 모든 KYB 세션에 걸쳐 집계된 기능별 상태입니다. 현재 유일한 키는 `KYB`(법인 등기부 기업 확인
            상태)입니다. 가능한 값: `Approved`, `Declined`, `In Review`, `Not Finished`,
            `Resub Requested`.
        features_list:
          type: array
          items:
            type: object
            properties:
              feature:
                type: string
              status:
                type: string
          description: '`features`와 동일한 데이터로, `{feature, status}` 객체의 정렬된 배열입니다.'
        last_session_at:
          type: string
          format: date-time
          nullable: true
          description: 가장 최근 세션의 타임스탬프
        first_session_at:
          type: string
          format: date-time
          nullable: true
          description: 첫 번째 세션의 타임스탬프
        last_activity_at:
          type: string
          format: date-time
          nullable: true
          description: 가장 최근 활동(상태 변경, 세션 업데이트 등)의 타임스탬프
        tags:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                format: uuid
              name:
                type: string
              color:
                type: string
          description: 이 기업에 할당된 태그
        created_at:
          type: string
          format: date-time
  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.