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

핵심 사용자 엔티티 관리는 /v3/users/ 아래의 공개 endpoint를 통해 이루어집니다. 가져온 얼굴 업로드와 같은 프로필 첨부 파일은 didit_internal_id를 사용하는 조직/애플리케이션 경로를 사용합니다. 이 페이지는 개념적인 흐름을 설명합니다. 요청 및 응답 스키마 전체는 API 참조를 확인하십시오.

사용자 목록 조회

GET /v3/users/ 애플리케이션의 사용자 목록을 페이지 단위로 반환합니다. 상태, 검색어, 날짜 범위 등으로 필터링할 수 있습니다.

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로 단일 사용자를 조회합니다. 집계 카운터를 포함한 전체 데이터 모델을 반환합니다.

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

URL의 vendor_data는 대소문자를 구분합니다. 세션을 생성할 때 사용한 값을 정확히 그대로 전달하십시오.

사용자 생성

POST /v3/users/create/ 세션이 실행되기 전에 사용자 엔티티를 생성합니다. 다음과 같은 경우에 유용합니다.

고객이 인증하기 전에 메타데이터나 사용자 지정 필드를 미리 입력합니다.
초기 상태를 설정합니다(예: 온보딩 팀이 수동 문서를 검토하는 동안 FLAGGED로 설정).
기존 데이터베이스의 사용자를 미리 불러와 첫날부터 전체 사용자 명단을 갖춥니다.

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입니다. 검사 항목과 오류는 사용자 생성을 참조하십시오.

가져온 얼굴 업로드

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ 신뢰할 수 있는 얼굴 이미지를 기존 사용자 프로필에 첨부합니다. 다른 제공업체에서 사용자를 가져왔고 첫 Didit 세션 전에 얼굴 증거를 Didit에 넘기려는 경우에 적합한 후속 작업입니다.

# 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, 차단 목록과의 차이는 사용자 얼굴 업로드를 참조하십시오.

사용자 업데이트

PATCH /v3/users/{vendor_data}/ 변경 가능한 프로필 필드를 업데이트합니다. 검증된 세션에서 파생된 필드 대부분은 읽기 전용입니다. PATCH로 이 필드를 변경하려고 하면 무시되거나 감사 로그에 표시됩니다. 변경 가능한 필드: display_name, metadata, tags. 인증 후 읽기 전용 필드: full_name, date_of_birth, portrait_image, 모든 집계 카운터, features 맵.

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 사이에서 변경합니다. 상태 변경은 이후 세션과 거래에 반영됩니다.

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/ 사용자 한 명 이상을 삭제합니다. 사용자 레코드는 세션 삭제 후 보관된 모든 생체 인식 템플릿과 함께 영구적으로 제거됩니다. 이 endpoint는 사용자의 인증 세션을 다루지 않으며, 세션은 사용자와의 연결이 해제된 상태로 남습니다. 세션은 세션 삭제 또는 세션 일괄 삭제로 삭제하십시오. 거래도 포함되지 않으므로 Console에서 삭제하십시오.

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 키에는 사용자(users) 액세스가 필요합니다. GET endpoint에는 읽기 권한이, 생성, 업데이트, 상태 변경, 삭제에는 쓰기 권한이 필요합니다. send_verification_link: true로 사용자를 생성하려면 세션 쓰기 권한도 필요합니다. 세션을 생성하고 그 링크를 이메일로 보내기 때문입니다. 필요한 액세스가 없는 키는 403으로 응답합니다. 일부 워크플로나 승인된 세션으로만 제한된 키는 /v3/users/* endpoint에 전혀 접근할 수 없습니다. 역할은 Console의 개념입니다. users 권한 리소스와 그 클레임이 팀원이 Console에서 할 수 있는 작업을 결정하며, API 키 요청에는 평가되지 않습니다. 해당 매트릭스는 역할 및 권한을 참조하십시오. 서비스가 사용자를 삭제하지 못하도록 하려면 사용자 읽기 권한만 있거나 사용자 액세스 권한이 없는 키를 부여하십시오.

속도 제한 및 멱등성

모든 /v3/users/* endpoint는 표준 속도 제한의 적용을 받습니다.
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`	없음. 삭제에 대응해야 한다면 자체 시스템에 삭제 사실을 기록하십시오

다음 단계

데이터 모델

전체 필드 참조.

목록 API

GET /v3/users/ 스키마.

생성 API

POST /v3/users/create/ 스키마.

얼굴 업로드

가져온 얼굴 이미지를 사용자 프로필에 첨부합니다.

개요

요금

워크플로 및 인증

검토 및 운영

엔터티(사용자 및 기업)

설정 및 사용자 지정

보안 및 컴플라이언스

Didit Academy

리소스

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

사용자 목록 조회

사용자 조회

사용자 생성

가져온 얼굴 업로드

사용자 업데이트

상태 변경

사용자 삭제(일괄)

권한 모델

속도 제한 및 멱등성

이 작업으로 발생하는 webhook

다음 단계

데이터 모델

목록 API

생성 API

얼굴 업로드

​사용자 목록 조회

​사용자 조회

​사용자 생성

​가져온 얼굴 업로드

​사용자 업데이트

​상태 변경

​사용자 삭제(일괄)

​권한 모델

​속도 제한 및 멱등성

​이 작업으로 발생하는 webhook

​다음 단계

데이터 모델

목록 API

생성 API

얼굴 업로드

사용자 목록 조회

사용자 조회

사용자 생성

가져온 얼굴 업로드

사용자 업데이트

상태 변경

사용자 삭제(일괄)

권한 모델

속도 제한 및 멱등성

이 작업으로 발생하는 webhook

다음 단계