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

# 사용자 CRUD: 벤더 사용자 관리 API

> Didit Management API로 벤더 사용자 엔티티를 생성, 조회, 수정, 상태 변경, 삭제합니다. 종량제 요금이며 계약은 필요 없습니다.



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



      
      

\<pre>

\````# Goal — full CRUD over Didit User entities

Core CRUD operations sit under `https://verification.didit.me/v3/users/` authenticated with `x-api-key: $DIDIT_API_KEY`. Profile attachment endpoints use the organization/application path and the User's `didit_internal_id`. Each User is keyed by `vendor_data` (case-sensitive, unique per application).

\## Endpoint catalog

\| Action | Method + path |
\|---|---|
\| List users | `GET /v3/users/` |
\| Get one user | `GET /v3/users/{vendor_data}/` |
\| Create user | `POST /v3/users/create/` |
\| Upload profile face | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` |
\| Update profile | `PATCH /v3/users/{vendor_data}/` |
\| Change status | `PATCH /v3/users/{vendor_data}/update-status/` |
\| Batch delete | `POST /v3/users/delete/` |

\## List (with filters)

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

\## Get one user

\```bash
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

\## Create

\```bash
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_source": "web"}
}'
\```

Not idempotent — retrying with the same `vendor_data` returns conflict. `GET` first or PATCH instead.

\## Upload an imported profile face

\```bash
\# First read didit_internal_id from GET /v3/users/{vendor_data}/
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

This attaches a trusted face image to the User profile and enrolls it for duplicate detection and face search. It does not add the face to a blocklist.

\## Update profile

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

Mutable: `display_name`, `metadata`, `tags`. Read-only (verified): `full_name`, `date_of_birth`, `portrait_image`, all aggregate counters, `features` map.

\## Change status

\```bash
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "BLOCKED", "reason": "Chargeback fraud pattern"}'
\```

Valid statuses: `ACTIVE`, `FLAGGED`, `BLOCKED`. `BLOCKED` users have new sessions auto-declined.

\## Batch delete

\```bash
curl -X POST https://verification.didit.me/v3/users/delete/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"vendor_data_list": ["user-42", "user-43", "user-44"]}'
\```

Idempotent — already-deleted is a no-op. Returns a count, `{"deleted": <int>}`, not a per-item result. The user records and every biometric template retained for them are removed permanently. Verification sessions are not covered by this endpoint; delete those with the session delete endpoints.

\## Webhooks fired

\| Operation | Event |
\|---|---|
\| create | none for the create call itself — the first `user.data.updated` arrives when a session or a PATCH first fills the profile |
\| update (PATCH) | `user.data.updated` with `changed_fields` |
\| update-status | `user.status.updated` |
\| delete | none — record the deletion on your own side if you need to react to it |

\## Failure modes

\- `401` — missing / invalid `x-api-key`.
\- `403` — the API key is not valid for this application.
\- `409` on create — `vendor_data` already exists; switch to PATCH.
\- `404` — no entity for that `vendor_data` (case-sensitive!).
\- `429` — rate-limited; back off using `Retry-After`.

\## Response shape

See /reference/data-models and /entities/users/data-model for the full User schema.

\## Sources of truth

\- /management-api/users/list, /management-api/users/get, /management-api/users/create — per-endpoint reference
\- /entities/users/data-model — field-by-field schema
\- /entities/webhooks — entity event payloads
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

붙여넣을 곳

핵심 사용자 엔티티 관리는 `/v3/users/` 아래의 공개 endpoint를 통해 이루어집니다. 가져온 얼굴 업로드와 같은 프로필 첨부 파일은 `didit_internal_id`를 사용하는 조직/애플리케이션 경로를 사용합니다. 이 페이지는 개념적인 흐름을 설명합니다. 요청 및 응답 스키마 전체는 [API 참조](https://docs.didit.me/ko/management-api/users/list.md)를 확인하십시오.## 사용자 목록 조회**`GET /v3/users/`**애플리케이션의 사용자 목록을 페이지 단위로 반환합니다. 상태, 검색어, 날짜 범위 등으로 필터링할 수 있습니다.```bash theme={null}
curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"
```사용 사례:- 매일 사용자 일부를 데이터 웨어하우스에 동기화합니다.
- 분석가 대기열에 올릴 플래그가 지정된 사용자를 찾습니다.
- 표시 이름으로 사용자를 검색합니다.## 사용자 조회**`GET /v3/users/{vendor_data}/`**`vendor_data`로 단일 사용자를 조회합니다. 집계 카운터를 포함한 전체 [데이터 모델](https://docs.didit.me/ko/entities/users/data-model.md)을 반환합니다.```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```> [!NOTE]
>
> URL의 `vendor_data`는 대소문자를 구분합니다. 세션을 생성할 때 사용한 값을 정확히 그대로 전달하십시오.## 사용자 생성**`POST /v3/users/create/`**세션이 실행되기 전에 사용자 엔티티를 생성합니다. 다음과 같은 경우에 유용합니다.- 고객이 인증하기 전에 메타데이터나 사용자 지정 필드를 미리 입력합니다.
- 초기 상태를 설정합니다(예: 온보딩 팀이 수동 문서를 검토하는 동안 `FLAGGED`로 설정).
- 기존 데이터베이스의 사용자를 미리 불러와 첫날부터 전체 사용자 명단을 갖춥니다.```bash theme={null}
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_source": "web" }
  }'
```같은 `vendor_data`를 가진 사용자가 이미 있으면 호출은 충돌 오류를 반환합니다. 대신 `PATCH`를 사용하여 업데이트하십시오.연락처 정보도 함께 보낼 수 있습니다. `first_name`과 `last_name`은 `full_name`을 보내지 않으면 하나로 합쳐집니다. 그 밖에 `email`, `phone_number`, `country`도 보낼 수 있습니다.
Didit은 `email`과 `phone_number`를 `metadata.contact`에, `country`를 `metadata.address`에 저장합니다.같은 호출에서 본인 인증을 요청하려면 `email`과 `workflow_id`와 함께 `send_verification_link: true`를 추가하십시오.
Didit은 해당 워크플로에 대한 인증 세션을 생성하고 인증 링크를 이메일로 보냅니다.
응답의 `verification_link`에는 세션의 `session_id`, `session_number`, `status`, `url`, `workflow_id`, `email`이 포함되며, 링크를 요청하지 않으면 `null`입니다.
검사 항목과 오류는 [사용자 생성](https://docs.didit.me/ko/management-api/users/create.md#인증-링크-보내기)을 참조하십시오.## 가져온 얼굴 업로드**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**신뢰할 수 있는 얼굴 이미지를 기존 사용자 프로필에 첨부합니다. 다른 제공업체에서 사용자를 가져왔고 첫 Didit 세션 전에 얼굴 증거를 Didit에 넘기려는 경우에 적합한 후속 작업입니다.```bash theme={null}
# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```요청 필드, 제한, 목록 및 삭제 endpoint, 차단 목록과의 차이는 [사용자 얼굴 업로드](https://docs.didit.me/ko/management-api/users/upload-face.md)를 참조하십시오.## 사용자 업데이트**`PATCH /v3/users/{vendor_data}/`**변경 가능한 프로필 필드를 업데이트합니다. 검증된 세션에서 파생된 필드 대부분은 읽기 전용입니다. PATCH로 이 필드를 변경하려고 하면 무시되거나 감사 로그에 표시됩니다.**변경 가능한 필드:** `display_name`, `metadata`, `tags`.
**인증 후 읽기 전용 필드:** `full_name`, `date_of_birth`, `portrait_image`, 모든 집계 카운터, `features` 맵.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
````changed_fields` 배열과 함께 `user.data.updated` webhook 이벤트를 발생시킵니다.## 상태 변경**`PATCH /v3/users/{vendor_data}/update-status/`**사용자의 상태를 `ACTIVE`, `FLAGGED`, `BLOCKED` 사이에서 변경합니다. 상태 변경은 이후 세션과 거래에 반영됩니다.```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'
```| 변경 전 → 변경 후 | 일반적인 트리거 |
| - | - |
| `ACTIVE` → `FLAGGED` | 거래 규칙, 분석가 검토, 지속적인 AML 모니터링에서의 적중 |
| `ACTIVE` → `BLOCKED` | 확인된 사기, 수동 차단 목록 등록, 차단 목록 일치 |
| `FLAGGED` → `ACTIVE` | 분석가가 검토 결과 문제없음으로 처리 |
| `BLOCKED` → `ACTIVE` | 분석가의 수동 차단 해제 |`user.status.updated` webhook 이벤트를 발생시킵니다.## 사용자 삭제(일괄)**`POST /v3/users/delete/`**사용자 한 명 이상을 삭제합니다. 사용자 레코드는 세션 삭제 후 보관된 모든 [생체 인식 템플릿](https://docs.didit.me/ko/management-api/biometric-templates/overview.md)과 함께 영구적으로 제거됩니다. 이 endpoint는 사용자의 인증 세션을 다루지 않으며, 세션은 사용자와의 연결이 해제된 상태로 남습니다. 세션은 [세션 삭제](https://docs.didit.me/ko/sessions-api/delete-session.md) 또는 [세션 일괄 삭제](https://docs.didit.me/ko/management-api/sessions/batch-delete.md)로 삭제하십시오. 거래도 포함되지 않으므로 Console에서 삭제하십시오.```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'
````vendor_data_list`, `didit_internal_id_list`, 또는 두 가지를 동시에 사용해 사용자를 선택하거나, `delete_all: true`를 전달해 애플리케이션의 모든 사용자를 삭제할 수 있습니다. Console의 `filter_*` 일괄 파라미터는 무시되지 않고 `400`으로 거부됩니다. 따라서 범위를 좁히려던 요청이 전체 삭제로 바뀌는 일이 없습니다.응답은 항목별 결과가 아니라 개수, `{"deleted": <int>}`를 반환합니다. 일치하는 항목이 없는 식별자는 조용히 건너뜁니다. 보낸 식별자 수와 `deleted`를 비교하려면 중복을 제거한 목록을 보내십시오.## 권한 모델API 키는 하나의 애플리케이션에 속합니다.
기본 비밀 키와 전체 액세스 키는 `delete`를 포함하여 해당 애플리케이션의 모든 `/v3/users/*` endpoint를 호출할 수 있습니다.[범위가 제한된 API 키](https://docs.didit.me/ko/console/api-keys.md)에는 **사용자**(`users`) 액세스가 필요합니다. `GET` endpoint에는 읽기 권한이, 생성, 업데이트, 상태 변경, 삭제에는 쓰기 권한이 필요합니다.
`send_verification_link: true`로 사용자를 생성하려면 **세션** 쓰기 권한도 필요합니다. 세션을 생성하고 그 링크를 이메일로 보내기 때문입니다.
필요한 액세스가 없는 키는 `403`으로 응답합니다.
일부 워크플로나 승인된 세션으로만 제한된 키는 `/v3/users/*` endpoint에 전혀 접근할 수 없습니다.역할은 Console의 개념입니다. `users` 권한 리소스와 그 클레임이 팀원이 Console에서 할 수 있는 작업을 결정하며, API 키 요청에는 평가되지 않습니다.
해당 매트릭스는 [역할 및 권한](https://docs.didit.me/ko/console/roles-permissions.md)을 참조하십시오.서비스가 사용자를 삭제하지 못하도록 하려면 **사용자** 읽기 권한만 있거나 **사용자** 액세스 권한이 없는 키를 부여하십시오.## 속도 제한 및 멱등성- 모든 `/v3/users/*` endpoint는 표준 [속도 제한](https://docs.didit.me/ko/integration/rate-limiting.md)의 적용을 받습니다.
- `create`는 멱등성이 **없습니다**. 같은 `vendor_data`로 재시도하면 충돌이 반환됩니다. 자체적으로 중복을 제거하거나 항상 먼저 `GET`을 호출하십시오.
- `delete`는 멱등성이 있습니다. 이미 삭제된 사용자를 삭제해도 아무 작업도 일어나지 않습니다.## 이 작업으로 발생하는 webhook| 작업 | Webhook |
| - | - |
| `create` | create 호출 자체에서는 webhook이 발생하지 않습니다. 첫 번째 `user.data.updated`는 세션이나 업데이트가 프로필을 처음 채울 때 도착합니다 |
| `update` | `user.data.updated` (`changed_fields` 포함) |
| `update-status` | `user.status.updated` |
| `delete` | 없음. 삭제에 대응해야 한다면 자체 시스템에 삭제 사실을 기록하십시오 |## 다음 단계> [card] [데이터 모델](https://docs.didit.me/ko/entities/users/data-model.md)
>
> 전체 필드 참조.> [card] [목록 API](https://docs.didit.me/ko/management-api/users/list.md)
>
> GET /v3/users/ 스키마.> [card] [생성 API](https://docs.didit.me/ko/management-api/users/create.md)
>
> POST /v3/users/create/ 스키마.> [card] [얼굴 업로드](https://docs.didit.me/ko/management-api/users/upload-face.md)
>
> 가져온 얼굴 이미지를 사용자 프로필에 첨부합니다.


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