> ## 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. # 얼굴 업로드 API: 생체 정보 목록 > base64 얼굴 이미지를 Didit 얼굴 차단 목록 또는 허용 목록에 업로드합니다. Didit이 생체 정보를 추출해 이후 얼굴 대조에 사용합니다. List API에 얼굴 업로드 프롬프트 프롬프트를 클립보드에 복사 \

\`Upload a face image directly to a Didit face blocklist or allowlist through the Management API.

Endpoint:
POST https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs workflows: write.

Goal:
\- Add a face to a face blocklist or allowlist when I do not have a verification session to reference. Didit detects the faces in the image, keeps the largest one, stores the image and a crop of that face, computes a biometric face template that new sessions are compared against, and creates the entry.
\- A face blocklist entry declines future sessions whose face matches. A face allowlist entry stops a matching face from triggering the duplicated-face action, but does not override blocklist matches or the other checks.

When NOT to use this:
\- If I am listing a face from an existing verification session, use POST /v3/lists/{list_uuid}/entries/ with reference_session_id instead, so the entry links back to the session.

Path parameter:
\- list_uuid: must be a list with entry_type "face" and list_type "blocklist" or "allowlist". Other lists return 400.

Request body (application/json):
\{
"image": "/9j/4AAQSkZ...",        // required: base64-encoded JPEG or PNG, at most 2 MB once decoded. Do not include a "data:image/..." prefix.
"comment": "Known fraud attempt"  // optional
}

Important constraints:
\- The image must show a clearly visible face. If no face is detected, the API returns 400 and no entry is created. If it shows several faces, Didit uses the largest one.
\- In a sandbox application the image is not analysed or stored: the entry has display_label "Sandbox face entry" and metadata.sandbox true, and matches nothing.

Example call:
curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"image": "/9j/4AAQSkZ...", "comment": "Known fraud attempt"}'

Example response (201):
\{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"value": "44444444-5555-6666-7777-888888888888",
"display_label": "Manually uploaded face",
"comment": "Known fraud attempt",
"added_by": "api",
"reference_session_id": null,
"reference_session_number": null,
"reference_session_type": null,
"reference_object_uuid": "44444444-5555-6666-7777-888888888888",
"metadata": { "reference_image_url": "https:///face_reference_image.jpg" },
"created_at": "2026-10-12T10:12:18.904467Z"
}

value and reference_object_uuid are the UUID of the new face. metadata.reference_image_url is a short-lived signed URL (null for a scoped key without media: read).

Failure modes:
\- 400: the list is not a face list ({ "detail": "Face upload is only available for face-type lists." }), the list is a custom face list, image is missing, larger than 2 MB, not valid base64, not a readable JPEG or PNG, or shows no face ({ "image": "No face detected in the image. Please upload a clear photo with a visible face." }).
\- 401: the API key has expired.
\- 403: missing x-api-key (a wrong, revoked or expired key gets 401) ({ "detail": "You do not have permission to perform this action." }), or a scoped key without workflows: write.
\- 404: list not found in this application ({ "detail": "List not found." }).
\- 503: face analysis is temporarily unavailable; no entry was created, retry later.
\- 429: rate limited (see /integration/rate-limiting); back off and retry.

Side effects:
\- The face template is added to biometric matching. Future sessions matching a blocklisted face are declined. Future sessions matching an allowlisted face skip the duplicated-face action and include an informational allowlist warning.

For the full integration shape, see /integration/integration-prompt.`

\
붙여넣을 곳 base64로 인코딩된 얼굴 이미지를 얼굴 차단 목록 또는 허용 목록에 업로드합니다. Didit는 이미지에서 얼굴을 감지하고 가장 큰 얼굴 하나를 남긴 뒤, 이미지와 해당 얼굴을 자른 이미지를 저장하고, 이후 새 세션과 비교할 생체 인식 템플릿을 계산합니다. 새 항목의 `value`는 해당 얼굴의 UUID입니다.`entry_type: face`이고 `list_type: blocklist` 또는 `list_type: allowlist`인 목록에서만 사용할 수 있습니다.> [!TIP] > > **기존 세션**의 얼굴을 차단 목록이나 허용 목록에 추가하려면 `reference_session_id`를 사용하는 [항목 생성](https://docs.didit.me/ko/management-api/lists/create-entry.md)을 대신 사용하세요. 이 경우 항목이 해당 세션에 연결됩니다.> [!WARNING] > > 이미지에는 명확하게 보이는 얼굴이 있어야 하며, 디코딩 후 크기는 최대 2 MB여야 합니다. 얼굴이 감지되지 않으면 요청은 `400`을 반환하고 항목은 생성되지 않습니다. 얼굴 분석을 일시적으로 사용할 수 없으면 `503`을 반환하므로 나중에 다시 시도하세요.얼굴을 목록에서 제거하려면 [해당 항목을 삭제](https://docs.didit.me/ko/management-api/lists/delete-entry.md)하세요. 삭제하면 새 세션과 더 이상 일치하지 않습니다. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/lists/{list_uuid}/entries/face-upload/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/lists/{list_uuid}/entries/face-upload/: post: tags: - Lists summary: 목록에 얼굴 업로드 description: >- 참조할 인증 세션이 없을 때를 위해 base64로 인코딩된 JPEG 또는 PNG 이미지로부터 얼굴 차단 목록 또는 얼굴 허용 목록에 얼굴을 추가합니다. Didit은 이미지에서 얼굴을 감지하여 가장 큰 얼굴을 사용하고, `value`와 `reference_object_uuid`가 새 얼굴의 UUID인 항목을 생성합니다. 차단 목록에 등록된 얼굴은 얼굴이 일치하는 새 세션을 거부하며, 허용 목록에 등록된 얼굴은 중복 얼굴 작업을 건너뛰고 차단 목록 일치 항목을 재정의하지 않습니다. 샌드박스 애플리케이션에서는 이미지가 분석되지 않으며 해당 항목은 어떤 것과도 일치하지 않습니다. 스코프가 지정된 API 키에는 `workflows: write` 권한이 필요합니다. 기존 세션에서 얼굴을 목록에 추가하려면 대신 `reference_session_id`와 함께 [목록 항목 생성](https://docs.didit.me/ko/management-api/lists/create-entry)을 사용하세요. operationId: upload_list_entry_face parameters: - name: list_uuid in: path required: true description: >- `entry_type: face` 및 `list_type: blocklist` 또는 `allowlist`인 목록의 UUID입니다. schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- 디코딩 시 최대 2MB 크기의 얼굴이 선명하게 보이는 Base64 인코딩된 JPEG 또는 PNG입니다. `data:image/...;base64,` 접두사 없이 순수 Base64 문자열만 전송해야 합니다. comment: type: string default: '' description: 목록 등록 사유 등과 같은 선택적 자유 텍스트 메모입니다. examples: Face image: value: image: /9j/4AAQSkZJRgABAQAAAQABAAD... comment: Known fraud attempt responses: '201': description: 얼굴 항목이 생성되었습니다. content: application/json: schema: $ref: '#/components/schemas/ComplianceListEntry' examples: Uploaded face: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Manually uploaded face comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: reference_image_url: >- https://media.example.com/faces/reference.jpg?expires=1760263938&signature=3f9a1c created_at: '2026-10-12T10:12:18.904467Z' Sandbox application: value: uuid: cccccccc-dddd-eeee-ffff-000000000000 value: 44444444-5555-6666-7777-888888888888 display_label: Sandbox face entry comment: Known fraud attempt added_by: api reference_session_id: null reference_session_number: null reference_session_type: null reference_object_uuid: 44444444-5555-6666-7777-888888888888 metadata: sandbox: true created_at: '2026-10-12T10:12:18.904467Z' '400': description: >- 목록이 얼굴 업로드를 지원하지 않거나 이미지가 누락되었거나 유효하지 않거나 너무 크거나 사용할 수 있는 얼굴이 표시되지 않습니다. 항목이 생성되지 않았습니다. content: application/json: examples: Not a face list: value: detail: Face upload is only available for face-type lists. Custom face list: value: detail: >- Face upload is only available for face blocklists and allowlists. Missing image: value: image: - This field is required. Invalid base64: value: image: - Invalid base64 encoding. Too large: value: image: - Image exceeds maximum size of 2 MB. Unreadable image: value: image: Invalid image. Provide a valid base64-encoded JPG or PNG. No face: value: image: >- No face detected in the image. Please upload a clear photo with a visible face. No usable face: value: image: Could not extract face embedding. Try a different image. '401': description: 스코프가 지정된 API 키가 만료되었습니다. 기타 인증 실패 시에는 `403`이 반환됩니다. content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- `x-api-key` 헤더가 누락되었거나(잘못되었거나 해지되었거나 만료된 키는 `401` 반환), 범위가 지정된 API 키에 `workflows: write` 권한이 없거나 허용 목록 외부의 IP 주소에서 사용되었습니다. content: application/json: examples: Missing or invalid API key: value: detail: You do not have permission to perform this action. Scoped key without workflows access: value: detail: This API key has no write access to workflows. '404': description: API 키의 애플리케이션에 이 UUID를 가진 목록이 존재하지 않거나 삭제되었습니다. content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: 얼굴 분석을 일시적으로 사용할 수 없습니다. 항목이 생성되지 않았으므로 나중에 다시 시도하십시오. content: application/json: examples: Unavailable: value: detail: Service temporarily unavailable. Please try again later. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/face-upload/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d "{\"image\": \"$(base64 < face.jpg | tr -d '\n')\", \"comment\": \"Known fraud attempt\"}" - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image="/9j/4AAQSkZJRgABAQAAAQABAAD...", comment="Known fraud attempt", ) print(result) - lang: javascript label: Node.js source: >- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.lists.entries.uploadFace("11111111-2222-3333-4444-555555555555", { image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n\tComment: didit.String(\"Known fraud attempt\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.ListsEntriesUploadFaceParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.lists().entries().uploadFace("11111111-2222-3333-4444-555555555555", ListsEntriesUploadFaceParams.builder() .image("/9j/4AAQSkZJRgABAQAAAQABAAD...") .comment("Known fraud attempt") .build()); System.out.println(result); - lang: php label: PHP source: >- lists->entries->uploadFace('11111111-2222-3333-4444-555555555555', [ 'image' => '/9j/4AAQSkZJRgABAQAAAQABAAD...', 'comment' => 'Known fraud attempt', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.lists.entries.upload_face( "11111111-2222-3333-4444-555555555555", image: "/9j/4AAQSkZJRgABAQAAAQABAAD...", comment: "Known fraud attempt" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Lists.Entries.UploadFaceAsync("11111111-2222-3333-4444-555555555555", new ListsEntriesUploadFaceParams { Image = "/9j/4AAQSkZJRgABAQAAAQABAAD...", Comment = "Known fraud attempt", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: ComplianceListEntry: type: object description: 목록 내의 값 1개입니다. required: - uuid - value - display_label - comment - added_by - reference_session_id - reference_session_number - reference_session_type - reference_object_uuid - metadata - created_at properties: uuid: type: string format: uuid description: 항목 식별자. 목록 항목 삭제에서 `entry_uuid`로 사용합니다. value: type: string description: >- 목록에 등록된 값: E.164 형식의 전화번호, 이메일 주소, 문서 번호, IP 주소 또는 CIDR 범위, 기기 지문, 지갑 주소, 은행 계좌, ISO 3166-1 alpha-3 국가 코드, `vendor_data`, `key` 목록의 모든 문자열, 또는 얼굴 목록에 저장된 얼굴의 UUID입니다. 전송하는 값은 전화번호와 국가 코드를 제외하고 소문자로 저장됩니다. 일치 여부 확인 시 대소문자를 구분하지 않습니다. display_label: type: string nullable: true maxLength: 512 description: >- 사람이 읽기 쉬운 라벨입니다. 아무것도 전송하지 않으면 Didit이 세션에서 가져온 항목(예: 소지자의 성명 및 문서 번호)으로 채웁니다. comment: type: string description: 자유 형식 메모입니다. 설정되지 않은 경우 빈 문자열입니다. added_by: type: string nullable: true description: >- 항목을 추가한 주체: `api`(API 키), 콘솔 사용자의 이메일 주소 또는 `console`, `system` 또는 `migration`(Didit이 생성한 항목), 또는 `rule`(거래 규칙 또는 모니터링 규칙의 작업). reference_session_id: type: string format: uuid nullable: true description: 해당 항목을 가져온 인증 세션입니다. 항목이 값으로 직접 추가된 경우 `null`입니다. reference_session_number: type: integer nullable: true description: 콘솔에 표시되는 해당 세션의 애플리케이션별 번호입니다. reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: 개인 인증 세션인 경우 `kyc`, 기업 확인 세션인 경우 `kyb`, 세션이 없는 경우 `null`입니다. reference_object_uuid: type: string format: uuid nullable: true description: >- 항목이 나타내는 레코드입니다. 세션에서 읽은 얼굴, 문서, 전화번호 또는 이메일 레코드, 목록에 얼굴 업로드를 통해 생성된 얼굴, 또는 전송한 UUID(예: 거래 UUID 또는 사용자의 `didit_internal_id`)입니다. metadata: type: object nullable: true additionalProperties: true description: >- 추가 컨텍스트입니다. 항목 생성 시 전송한 `metadata`와 병합된 Didit이 설정한 키(여기에 나열됨)가 포함되며, 저장된 그대로 반환됩니다. 없는 경우 `null`입니다. properties: reference_image_url: type: string description: >- 얼굴 항목: 호출마다 새로 발급되는 단기 서명된 URL입니다. `media: read` 권한이 없는 범위 지정 API 키의 경우 `null`입니다. 해당 항목에 이미지가 없으면 생략됩니다. front_image_url: type: string description: >- 문서 앞면 이미지를 포함하는 문서 항목: 호출할 때마다 다시 발급되는 수명이 짧은 서명된 URL입니다. `media: read` 권한이 없는 범위가 지정된 API 키의 경우 `null`입니다. full_name: type: string description: '세션에서 가져온 문서 항목: 소지자의 성명입니다.' issuing_state: type: string description: '세션에서 가져온 문서 항목: ISO 3166-1 alpha-3 발급 국가입니다.' document_type: type: string description: '세션에서 가져온 문서 항목: 문서 유형 코드(예: `P`, `ID`, `DL`)입니다.' region: type: string description: >- 세션에서 가져온 문서 항목: 지역에서 발급된 문서의 발급 주 또는 도이며, 해당하지 않는 경우 비어 있습니다. 세션 항목을 차단 목록에 추가해도 설정되지 않습니다. document_number: type: string description: '세션에서 가져온 문서 항목: 문서 번호입니다.' face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: '문서 캡처 셀피에서 가져온 얼굴 항목: 셀피 구분입니다. 라이브니스 얼굴인 경우 없습니다.' reference_node_id: type: string nullable: true description: '문서 캡처 셀피에서 가져온 얼굴 항목: 셀피가 생성된 신분증 인증 노드입니다.' fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: >- 세션에서 수집된 기기 핑거프린트 항목(핑거프린트가 파생된 방식)입니다. `persistent_id`는 단일 기기를 식별하며, `composite_hash` 및 `legacy_fp`는 동일한 모델의 기기 간에 공유될 수 있습니다. sandbox: type: boolean description: 샌드박스 애플리케이션에 업로드된 얼굴 항목인 경우 `true`입니다. 이러한 항목은 어떤 것과도 일치하지 않습니다. reference_type: type: string enum: - transaction - vendor_user - vendor_business description: >- 사용자가 직접 설정: 콘솔에서 다시 연결할 수 있도록 `reference_object_uuid`가 가리키는 대상입니다. reference_id: type: string description: '사용자가 직접 설정: 소스 레코드의 식별자입니다.' created_at: type: string format: date-time description: 항목이 추가된 시점입니다. responses: RateLimitedWrite: description: >- API 키당 분당 300개의 요청을 처리하는 공유 쓰기 속도 제한을 초과했습니다. 다시 시도하기 전에 `Retry-After`를 준수하십시오. content: application/json: schema: type: object required: - detail properties: detail: type: string example: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.