curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider"}'from didit import Didit
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
client = Didit()
result = client.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image="/9j/4AAQSkZJRgABAQEA...",
comment="Imported from previous KYC provider",
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
const didit = new Didit();
const result = await didit.users.uploadFace("11111111-2222-3333-4444-555555555555", {
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
client := didit.NewClient()
result, err := client.Users.UploadFace(ctx, "11111111-2222-3333-4444-555555555555", didit.UsersUploadFaceParams{
Image: "/9j/4AAQSkZJRgABAQEA...",
Comment: didit.String("Imported from previous KYC provider"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import me.didit.Didit;
import me.didit.types.UsersUploadFaceParams;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
Didit client = new Didit();
var result = client.users().uploadFace("11111111-2222-3333-4444-555555555555", UsersUploadFaceParams.builder()
.image("/9j/4AAQSkZJRgABAQEA...")
.comment("Imported from previous KYC provider")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
$didit = new DiditClient();
$result = $didit->users->uploadFace('11111111-2222-3333-4444-555555555555', [
'image' => '/9j/4AAQSkZJRgABAQEA...',
'comment' => 'Imported from previous KYC provider',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
didit = Didit::Client.new
result = didit.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
using var client = new DiditClient();
var result = await client.Users.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new UsersUploadFaceParams
{
Image = "/9j/4AAQSkZJRgABAQEA...",
Comment = "Imported from previous KYC provider",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"image_url": "https://signed-url.example/face.jpg",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}사용자 얼굴 업로드 API: 벤더 사용자 프로필
vendor_data로 사용자를 생성하거나 가져온 후, Didit의 기존 사용자 프로필에 base64 얼굴 이미지를 업로드합니다.
curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider"}'from didit import Didit
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
client = Didit()
result = client.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image="/9j/4AAQSkZJRgABAQEA...",
comment="Imported from previous KYC provider",
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
const didit = new Didit();
const result = await didit.users.uploadFace("11111111-2222-3333-4444-555555555555", {
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
client := didit.NewClient()
result, err := client.Users.UploadFace(ctx, "11111111-2222-3333-4444-555555555555", didit.UsersUploadFaceParams{
Image: "/9j/4AAQSkZJRgABAQEA...",
Comment: didit.String("Imported from previous KYC provider"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import me.didit.Didit;
import me.didit.types.UsersUploadFaceParams;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
Didit client = new Didit();
var result = client.users().uploadFace("11111111-2222-3333-4444-555555555555", UsersUploadFaceParams.builder()
.image("/9j/4AAQSkZJRgABAQEA...")
.comment("Imported from previous KYC provider")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
$didit = new DiditClient();
$result = $didit->users->uploadFace('11111111-2222-3333-4444-555555555555', [
'image' => '/9j/4AAQSkZJRgABAQEA...',
'comment' => 'Imported from previous KYC provider',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
didit = Didit::Client.new
result = didit.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
using var client = new DiditClient();
var result = await client.Users.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new UsersUploadFaceParams
{
Image = "/9j/4AAQSkZJRgABAQEA...",
Comment = "Imported from previous KYC provider",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"image_url": "https://signed-url.example/face.jpg",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}개요
다른 제공업체에서 사용자를 가져오고 각 사용자의 신뢰할 수 있는 얼굴 이미지가 이미 있는 경우 이 endpoint를 사용합니다. 사용자는 계속vendor_data로 식별되지만, 이 프로필 첨부 endpoint는 대상 사용자를 명확히 하기 위해 didit_internal_id를 사용합니다.
endpoint
POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/
마이그레이션 흐름
사용자 생성 또는 찾기
POST /v3/users/create/를 호출하고, 기존 프로필은 GET /v3/users/{vendor_data}/를 호출합니다.didit_internal_id 저장
didit_internal_id가 포함됩니다. 데이터베이스에서는 계속 vendor_data를 사용하고, didit_internal_id는 프로필 첨부 endpoint에서만 사용합니다.얼굴 업로드
image 필드에 원시 base64 이미지를 전송합니다. 백엔드는 저장하기 전에 이미지 디코딩, 이미지 크기, 얼굴 감지를 검증합니다.예제
# 1. Create the User keyed by your external id
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": { "previous_provider": "legacy-kyc-vendor" }
}'
# 2. Upload an imported face to the returned didit_internal_id
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"
}'
요청 본문
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
image | 문자열 | 예 | 원시 base64로 인코딩된 JPG 또는 PNG. data:image/...;base64,를 포함하지 마십시오. 디코딩 후 최대 크기: 2 MB. |
comment | 문자열 | 아니요 | 사용자 프로필에 표시되는 운영자용 메모. |
응답
{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"image_url": "https://signed-url.example/face.jpg",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}
검증 및 제한
- 사용자당 수동으로 업로드한 얼굴은 최대 5개입니다.
- 디코딩 후 이미지의 최대 크기는 2 MB입니다.
- 이미지는 유효한 base64여야 하며 이미지로 디코딩되어야 합니다.
- 이미지에는 감지 가능한 얼굴이 있어야 합니다. 가능하면 정면이고 조명이 좋은 얼굴 크롭을 사용하십시오.
- 업로드된 얼굴은 이후 중복 감지와 얼굴 검색을 위해 색인됩니다.
- 업로드된 얼굴은 자동으로 차단 목록에 추가되지 않습니다.
얼굴 목록 조회 또는 삭제
프로필 얼굴 목록 조회:curl https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/ \
-H "x-api-key: YOUR_API_KEY"
curl -X DELETE https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/$FACE_UUID/ \
-H "x-api-key: YOUR_API_KEY"
권한
같은 애플리케이션의 API 키를 사용합니다. 해당 키는 대상 사용자 프로필을 관리할 수 있도록 허용된 앱에 속해 있어야 합니다.실패 상황
400: 잘못된 base64, 잘못된 이미지, 감지 가능한 얼굴 없음, 2 MB를 초과하는 이미지, 또는 사용자에게 이미 업로드된 얼굴이 5개 있는 경우.401: 자격 증명이 없거나 유효하지 않음.403: API 키는 유효하지만 이 사용자 프로필을 관리할 권한이 없음.404: 애플리케이션에 해당didit_internal_id를 가진 사용자가 없음.429: 속도 제한에 걸림.Retry-After를 사용하여 재시도 전에 대기하십시오.
관련 문서
인증
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 를 참고하십시오.
경로 매개변수
애플리케이션을 소유한 조직 UUID입니다.
사용자 프로필을 소유한 애플리케이션 UUID입니다.
GET /v3/users/{vendor_data}/ 및 POST /v3/users/create/에서 didit_internal_id로 반환되는 Didit 내부 사용자 UUID입니다.