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

# 벤더 데이터 연결: ID를 엔티티에 바인딩

> vendor_data 식별자는 고객 시스템과 Didit을 연결해 세션, 거래, 사용자/기업 엔티티를 하나의 프로필로 묶어 줍니다. 호출당 요금 과금.

Vendor Data 연결 프롬프트
프롬프트를 클립보드에 복사

<pre>
  \`\`\`\`# Goal — link every session, transaction, and entity together using `vendor_data`

  `vendor_data` is the string identifier you choose and pass on every API call to bind it to a persistent [User](https://docs.didit.me/entities/users/overview.md) or [Business](https://docs.didit.me/entities/businesses/overview.md) entity. Get this right once and you never have to re-key history afterwards.

  ## Rules

  * `vendor_data` is **opaque** to Didit. Use your stable internal customer id.
  * Choose one canonical id per entity and never change it. Changing it orphans history under a new entity.
  * Prefix by entity type when convenient (`user_...`, `biz_...`) to avoid collisions in your own code.
  * Keep it under 128 chars, case-sensitive stable. Hard limit is 2000 bytes (UTF-8 encoded) - anything over that is rejected with a 400 rather than accepted.
  * **Never put raw PII in it** — it surfaces in webhooks, logs, and API responses.
  * Uniqueness is per application × entity type. User `user-42` and Business `user-42` are different entities (but don't do this).

  ## Where it goes

  | API | Field |
  | - | - |
  | `POST /v3/session/` | top-level `vendor_data` (KYC and KYB) |
  | `POST /v3/transactions/` | top-level `vendor_data` and `applicant.vendor_data` / `counterparty.vendor_data` |
  | `POST /v3/users/create/` / `POST /v3/businesses/create/` | `vendor_data` |
  | `GET /v3/sessions?vendor_data=...` | query param to retrieve history |
  | `GET /v3/users/{vendor_data}/` / `GET /v3/businesses/{vendor_data}/` | path param |

  ## Pattern — pre-create the entity, then run a session

  ```bash
  # 1) Seed the entity with metadata before any session
  curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "vendor_data": "user-42",
  "display_name": "Jane Doe",
  "metadata": {"tier": "premium", "signup_date": "2026-04-01"}
  }'

  # 2) Run a KYC session linked to the same entity
  curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "workflow_id": "$WORKFLOW_ID",
  "vendor_data": "user-42",
  "callback": "https://myapp.com/return"
  }'

  # 3) Later, retrieve every session for the entity
  curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  --data-urlencode "vendor_data=user-42"
  ```

  ## Auto-create semantics

  If you create a session with a new `vendor_data` and no entity exists, Didit creates the entity automatically with `status: ACTIVE` and links the session.

  ## Failure modes

  * Missing `vendor_data` on session create → session is orphaned, won't appear in any entity profile, cannot be filtered by `vendor_data` later (only by `session_id`).
  * Different case (`User-42` vs `user-42`) → two separate entities. Pick a casing convention and stick to it.
  * Same `vendor_data` across staging and prod apps → no collision; `vendor_data` is scoped per application.

  ## Sources of truth

  * /entities/users/operations — full User CRUD
  * /entities/businesses/operations — full Business CRUD
  * /sessions-api/create-session — session body shape
  * /integration/integration-prompt — canonical end-to-end prompt\`\`\`\`
</pre>

붙여넣을 곳

`vendor_data`는 모든 세션과 거래에 함께 보내서 해당 항목을 [사용자](https://docs.didit.me/ko/entities/users/overview.md) 또는 [기업](https://docs.didit.me/ko/entities/businesses/overview.md) 엔티티에 연결하는 식별자입니다. 엔티티 집계에서 가장 중요한 필드이며, 이 값을 올바르게 설정하면 프로필 이력, 거래 모니터링, 차단 목록 적용, 지속적인 AML 모니터링 등 이후의 모든 기능이 원활하게 동작합니다.

## 개요

`vendor_data`는 직접 선택하는 **문자열**입니다. Didit은 이를 불투명한 식별자로 취급하며 내용을 해석하지 않습니다. 일반적인 값은 다음과 같습니다.

| 귀사의 시스템 | 적합한 `vendor_data` 값 |
| - | - |
| 내부 사용자 데이터베이스 | `user_1234`, 사용자의 `uuid-v4` |
| 고객 대상 ID | `CUST-2026-00042`, 해시된 이메일 |
| 멀티테넌트 SaaS | `tenant_acme:user_1234` |
| B2B 플랫폼 | `company-hq-global`, `tax-id-US-123456789` |

> [!WARNING]
>
> `vendor_data`에 PII(이메일, 전화번호, 원본 납세자 번호)를 **직접** 넣지 마십시오. 해시하거나 접두사를 붙이십시오. `vendor_data`는 webhook 페이로드에 나타나며, 엔티티가 존재하는 동안 무기한 저장됩니다.

## 연결 방식

```mermaid theme={null}
flowchart TD
    subgraph YourSystem["Your system"]
      Customer["Customer record: user-42"]
    end
    subgraph Didit["Didit platform"]
      Entity["User entity (vendor_data = user-42)"]
      S1[Session #1]
      S2[Session #2]
      T1[Transaction #1]
      T2[Transaction #2]
      F[Face biometric]
    end
    Customer -.vendor_data.-> Entity
    S1 --> Entity
    S2 --> Entity
    T1 --> Entity
    T2 --> Entity
    F --> Entity
```

`vendor_data` 값과 함께 세션 또는 거래를 제출하면 다음과 같이 처리됩니다.

1. Didit이 해당 `vendor_data`를 가진 엔티티를 귀사의 애플리케이션에서 찾습니다.
2. 엔티티가 있으면 새 객체를 그 엔티티에 연결합니다.
3. 엔티티가 없으면 Didit이 엔티티를 생성(`status: ACTIVE`)하고 새 객체를 연결합니다.

이 동작은 다음에 모두 적용됩니다.

* `POST /v3/session/` — KYC 및 기업 확인(KYB) 세션
* `POST /v3/transactions/` — 거래(신청자와 거래 상대방 모두에 대해)
* 거래 페이로드 내부의 `applicant.vendor_data` / `counterparty.vendor_data` 필드

## 고유성 및 적용 범위

`vendor_data`는 Didit 전체가 아니라 **애플리케이션별로 고유**합니다.

| 범위 | 고유성 보장 |
| - | - |
| 하나의 애플리케이션 내부 | `vendor_data`는 엔티티 유형별로 고유합니다(사용자와 기업은 별도의 네임스페이스입니다). |
| 귀사 조직 내 다른 애플리케이션 | `vendor_data`는 **공유되지 않습니다**. 두 앱의 같은 값은 서로 다른 두 엔티티를 가리킵니다. |
| 다른 조직 | 공유되지 않습니다. 모든 조직은 고유한 엔티티 테이블을 가집니다. |

따라서 스테이징 앱과 프로덕션 앱에서 같은 `vendor_data`를 사용해도 충돌이 발생하지 않습니다. 또한 사용자 `user-42`와 기업 `user-42`를 함께 사용해도 충돌하지 않지만, 명확성을 위해 권장하지 않습니다.

## `vendor_data`를 생략하면 발생하는 일

`vendor_data` 없이 세션을 생성할 수 있습니다. 이 경우 다음과 같습니다.

* 해당 세션에 대한 엔티티가 생성되지 않습니다.
* 세션이 고아 상태가 되며, 어떤 사용자 또는 기업 프로필에도 나타나지 않습니다.
* 나중에 `vendor_data`로 세션을 조회할 수 없습니다. `session_id`로만 조회할 수 있습니다.

이 방식은 엔티티 집계가 필요 없는 익명 또는 일회성 인증에만 사용하십시오. 재인증, 거래 또는 지속적인 모니터링이 포함된 모든 연동에서는 항상 `vendor_data`를 제공하십시오.

## 예시: 엔티티를 미리 생성한 뒤 세션 실행

```bash theme={null}
# 1. Pre-create the User with initial metadata
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_date": "2026-04-01" }
  }'

# 2. Create a User Verification (KYC) session for the same user
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyc_standard",
    "vendor_data": "user-42"
  }'

# 3. Later, submit a transaction tied to the same user
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "tx-0001",
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Acme Corp" }
  }'
```

세 가지 호출이 모두 같은 사용자 엔티티에 연결됩니다. 이후 `GET /v3/users/user-42/`를 호출하면 세션 수, 승인 및 거부 카운터, 연결된 거래, 최신 프로필 데이터를 확인할 수 있습니다.

## 외부 ID 마이그레이션

기존 KYC 공급업체에서 Didit으로 옮기는 경우, 처음부터 기존의 안정적인 사용자 ID를 `vendor_data`로 전달하십시오. 이렇게 하면 다음 작업이 쉬워집니다.

* Didit 데이터를 내부 데이터베이스와 대조합니다.
* 세션을 실행하기 전에 콘솔의 CSV 가져오기로 과거 사용자를 일괄 등록합니다.
* 나중에 거래 모니터링을 위해 Didit으로 마이그레이션할 때도 관계를 유지합니다.

## 규칙, 관례 및 권장 사항

| 규칙 | 이유 |
| - | - |
| 엔티티마다 기준 식별자를 하나만 정하고 절대 변경하지 마십시오. | 값을 변경하면 새 엔티티가 생성되고 이력이 고아 상태가 됩니다. |
| `vendor_data` 값에 엔티티 유형별 접두사(`user_...`, `biz_...`)를 붙이십시오. | 귀사의 코드에서 네임스페이스 간 우발적 충돌을 방지합니다. |
| `vendor_data`의 대소문자를 일관되게 유지하십시오. | Didit은 대소문자를 정규화하지 않습니다. |
| `vendor_data` 길이를 128자 미만으로 유지하십시오. | 데이터베이스 인덱스에 무리 없이 들어갑니다. |
| 원본 PII를 절대 노출하지 마십시오. | `vendor_data`는 webhook, 감사 로그, API 응답에 나타납니다. |

## 다음 단계

> [card] [사용자 개요](https://docs.didit.me/ko/entities/users/overview.md)
>
> 사용자 엔티티와 작업에 대한 자세한 설명입니다.

> [card] [기업 개요](https://docs.didit.me/ko/entities/businesses/overview.md)
>
> 기업 엔티티와 작업에 대한 자세한 설명입니다.

> [card] [세션 생성](https://docs.didit.me/ko/sessions-api/create-session.md)
>
> vendor\_data를 사용한 인증을 시작합니다.

> [card] [거래 생성](https://docs.didit.me/ko/management-api/transactions/create.md)
>
> 엔티티에 연결된 거래를 제출합니다.


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