> ## 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) CRUD 작업: 기업 엔티티 관리

> Didit Management API로 Didit 기업(KYB) 엔티티를 생성, 조회, 수정, 상태 변경, 삭제하는 전체 CRUD 기능. 호출당 과금되는 KYB.



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



      
      

\<pre>

\````# Goal — full CRUD over Didit Business (KYB) entities

All operations sit under `https://verification.didit.me/v3/businesses/` authenticated with `x-api-key: $DIDIT_API_KEY`. Each Business is keyed by `vendor_data` (case-sensitive, unique per application).

\## Endpoint catalog

\| Action | Method + path |
\|---|---|
\| List businesses | `GET /v3/businesses/` |
\| Get one business | `GET /v3/businesses/{vendor_data}/` |
\| Create business | `POST /v3/businesses/create/` |
\| Update profile | `PATCH /v3/businesses/{vendor_data}/` |
\| Change status | `PATCH /v3/businesses/{vendor_data}/update-status/` |
\| Batch delete | `POST /v3/businesses/delete/` |

\## List (with filters)

\```bash
curl -G https://verification.didit.me/v3/businesses/ \
-H "x-api-key: $DIDIT_API_KEY" \
\--data-urlencode "status=ACTIVE" \
\--data-urlencode "country_code=GBR" \
\--data-urlencode "page_size=50"
\```

\## Get one business

\```bash
curl https://verification.didit.me/v3/businesses/biz-acme/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

\## Create

\```bash
curl -X POST https://verification.didit.me/v3/businesses/create/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vendor_data": "biz-acme",
"display_name": "Acme Corp",
"country_code": "GBR",
"metadata": {"partner": "Acme Holdings"}
}'
\```

Not idempotent — a duplicate `vendor_data` returns conflict. `GET` first or PATCH.

\## Update profile

\```bash
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"metadata": {"tier": "enterprise"}}'
\```

Mutable: `display_name`, `metadata`, `tags`. Read-only (registry-derived after a KYB session): `legal_name`, `registration_number`, `country_code`, all aggregate counters, `features` map.

\## Change status

\```bash
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/update-status/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "BLOCKED", "reason": "Sanctioned subsidiary detected"}'
\```

Valid statuses: `ACTIVE`, `FLAGGED`, `BLOCKED`. `BLOCKED` businesses have new KYB sessions and transactions auto-declined.

\## Batch delete

\```bash
curl -X POST https://verification.didit.me/v3/businesses/delete/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"vendor_data": ["biz-acme", "biz-alpha", "biz-beta"]}'
\```

Idempotent. The business records are removed permanently. Verification sessions are not covered by this endpoint; delete those with the session delete endpoints.

\## Webhooks fired

\| Operation | Event |
\|---|---|
\| create | `business.data.updated` |
\| update (PATCH) | `business.data.updated` with `changed_fields` |
\| update-status | `business.status.updated` |
\| delete | `business.data.updated` with `deleted_at` set |

\## Running a KYB session against an existing Business

KYB sessions use the same `POST /v3/session/` endpoint as KYC — the workflow's `workflow_type: "kyb"` switches the session into business mode:

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"workflow_id": "$KYB_WORKFLOW_ID", "vendor_data": "biz-acme"}'
\```

\## Failure modes

\- `401` — missing / invalid `x-api-key`.
\- `403` — role lacks the permission (DEVELOPER can't PATCH; see /console/roles-permissions).
\- `409` on create — `vendor_data` exists; PATCH instead.
\- `404` — wrong `vendor_data` casing.
\- `429` — rate-limited; back off with `Retry-After`.

\## Response shape

See /reference/data-models and /entities/businesses/data-model for the full Business schema.

\## Sources of truth

\- /management-api/businesses/list, /management-api/businesses/get, /management-api/businesses/create — per-endpoint reference
\- /entities/businesses/data-model — field-by-field
\- /business-verification/integration-guide — KYB session flow
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

붙여넣을 곳

모든 기업 엔티티 관리는 `/v3/businesses/` 아래의 공개 endpoint 6개를 통해 이루어집니다. 이 페이지에서는 개념적인 흐름을 설명합니다. 전체 요청 및 응답 스키마는 [API 레퍼런스](https://docs.didit.me/ko/management-api/businesses/list.md)를 참고하세요.## 기업 목록 조회**`GET /v3/businesses/`**애플리케이션의 기업을 페이지 단위로 나누어 조회합니다. 상태, 검색어, 국가, 날짜 범위로 필터링할 수 있습니다.```bash theme={null}
curl -G https://verification.didit.me/v3/businesses/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "country_code=GBR" \
  --data-urlencode "page_size=50"
```## 기업 조회**`GET /v3/businesses/{vendor_data}/`**`vendor_data`로 기업 한 곳을 조회합니다.```bash theme={null}
curl https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY"
```## 기업 생성**`POST /v3/businesses/create/`**기업 확인(KYB) 세션을 실행하기 전에 기업을 미리 생성합니다.```bash theme={null}
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": "biz-acme",
    "display_name": "Acme Corp",
    "country_code": "GBR",
    "metadata": { "partner": "Acme Holdings" }
  }'
```같은 `vendor_data`를 가진 기업이 이미 있으면 충돌 오류를 반환합니다. 기존 기업을 수정하려면 `PATCH`를 사용하세요.## 기업 수정**`PATCH /v3/businesses/{vendor_data}/`**수정 가능한 프로필 필드를 업데이트합니다. 레지스트리 조회로 채워지는 필드(`legal_name`, `registration_number`, `country_code`)는 인증 후 읽기 전용이지만 재정의할 수 있습니다. 재정의한 내역은 감사 로그에 표시됩니다.**수정 가능한 필드:** `display_name`, `metadata`, `tags`.
**인증 후 읽기 전용:** 레지스트리에서 가져온 모든 필드, 집계 카운터, `features` 맵.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
````business.data.updated` 이벤트가 발생합니다.## 상태 변경**`PATCH /v3/businesses/{vendor_data}/update-status/`**기업의 상태를 `ACTIVE`, `FLAGGED`, `BLOCKED` 사이에서 변경합니다.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Sanctioned subsidiary detected in ownership chain"
  }'
```| 변경 | 일반적인 트리거 |
| - | - |
| `ACTIVE` → `FLAGGED` | 기업 확인(KYB) 세션이 `In Review` 상태로 바뀜, 지속적인 AML 모니터링 적중, 거래 규칙 |
| `ACTIVE` → `BLOCKED` | 제재 대상으로 확인된 기업, 수동 차단 목록 등록 |
| `FLAGGED` → `ACTIVE` | 분석가가 검토를 완료함 |
| `BLOCKED` → `ACTIVE` | 조치 후 수동으로 차단 해제 |`business.status.updated` 이벤트가 발생합니다.## 기업 일괄 삭제**`POST /v3/businesses/delete/`**하나 이상의 기업을 삭제합니다. 기업 레코드는 영구적으로 삭제됩니다. 이 endpoint는 기업의 인증 세션을 다루지 않습니다. 해당 세션은 기업과의 연결만 해제된 상태로 남아 있습니다. 세션을 삭제하려면 [세션 삭제](https://docs.didit.me/ko/sessions-api/delete-session.md)를 사용하세요. 거래도 이 endpoint의 대상이 아니므로 Console에서 삭제해야 합니다.```bash theme={null}
curl -X POST https://verification.didit.me/v3/businesses/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vendor_data": ["biz-acme", "biz-alpha", "biz-beta"] }'
```멱등성이 보장됩니다. 이미 삭제된 기업을 다시 삭제해도 아무 작업도 일어나지 않습니다.## 권한 모델`/v3/businesses/*` endpoint는 모두 `businesses` 권한 리소스에 따라 범위가 제한됩니다:| 역할 | list | get | create | update | update-status | delete |
| - | :-: | :-: | :-: | :-: | :-: | :-: |
| OWNER | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ADMIN | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| COMPLIANCE\_OFFICER | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ |
| DEVELOPER | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| READER | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |[역할 및 권한](https://docs.didit.me/ko/console/roles-permissions.md)을 참고하세요.## 이 작업에서 발생하는 webhook| 작업 | Webhook |
| - | - |
| `create` | `business.data.updated` |
| `update` | `changed_fields` 포함 `business.data.updated` |
| `update-status` | `business.status.updated` |
| `delete` | `deleted_at` 설정 포함 `business.data.updated` |## 다음 단계> [card] [데이터 모델](https://docs.didit.me/ko/entities/businesses/data-model.md)
>
> 전체 필드 참조.> [card] [목록 API](https://docs.didit.me/ko/management-api/businesses/list.md)
>
> GET /v3/businesses/ 스키마.> [card] [생성 API](https://docs.didit.me/ko/management-api/businesses/create.md)
>
> POST /v3/businesses/create/ 스키마.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.