> ## 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が生体情報を抽出し、以降の顔照合に使用します。 顔画像をリストにアップロードする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/ja/management-api/lists/create-entry.md)を使用してください。エントリーはそのセッションに紐付けられます。> [!WARNING] > > 画像には顔がはっきりと写っている必要があり、デコード後のサイズは2 MB以下でなければなりません。顔が検出されない場合、リクエストは`400`を返し、エントリーは作成されません。顔分析が一時的に利用できない場合は`503`を返します。時間をおいて再試行してください。リストから顔を削除するには、[そのエントリーを削除](https://docs.didit.me/ja/management-api/lists/delete-entry.md)します。削除すると、その顔は新しいセッションと照合されなくなります。 ## OpenAPI ````yaml ja/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/ja/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: >- Base64エンコードされたJPEGまたはPNG画像で、デコード後のサイズが最大2MB、かつ顔がはっきりと写っているものです。`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: このUUIDのリストがAPIキーのアプリケーションに存在しないか、削除されています。 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: >- エントリが表すレコード: セッションから読み取った顔、書類、電話番号またはメールアドレスのレコード、Upload a face to a listで作成された顔、または送信したUUID（例: 取引のUUIDやユーザーの`didit_internal_id`）。 metadata: type: object nullable: true additionalProperties: true description: >- 追加コンテキストです。Diditが設定するキー(ここに記載)と、エントリー作成時に送信した`metadata`をマージし、保存されたとおりに返します。ない場合は`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: >- セッションから取得した書類エントリ: 地域単位で発行された書類の発行州または県。該当しない場合は空。Add session items to the blocklistでは設定されません。 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`は1台のデバイスを識別します。`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: >- お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.