> ## 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 Unggah Wajah: Daftar Biometrik Didit > Unggah gambar wajah base64 ke daftar blokir atau izin wajah Didit. Didit mengekstrak biometrik dan memakainya untuk pencocokan wajah. Prompt API Unggah Wajah ke Daftar Salin prompt ke papan klip \

\`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.`

\
Tempel ke Unggah gambar wajah yang dienkode base64 ke daftar blokir atau daftar izin wajah. Didit mendeteksi wajah dalam gambar, mempertahankan wajah yang paling besar, menyimpan gambar dan potongan wajah tersebut, lalu menghitung templat biometrik wajah yang menjadi pembanding bagi sesi baru. Nilai `value` dari entri baru adalah UUID wajah tersebut.Hanya tersedia untuk daftar dengan `entry_type: face` dan `list_type: blocklist` atau `list_type: allowlist`.> [!TIP] > > Jika Anda ingin memasukkan wajah **dari sesi yang sudah ada** ke daftar blokir atau daftar izin, gunakan [Buat entri](https://docs.didit.me/id/management-api/lists/create-entry.md) dengan `reference_session_id` sebagai gantinya: entri tersebut akan tertaut kembali ke sesinya.> [!WARNING] > > Gambar harus memuat wajah yang terlihat jelas dan berukuran maksimal 2 MB setelah didekode. Jika tidak ada wajah yang terdeteksi, permintaan mengembalikan `400` dan tidak ada entri yang dibuat. Jika analisis wajah untuk sementara tidak tersedia, permintaan mengembalikan `503`: coba lagi nanti.Untuk menghapus wajah dari daftar, [hapus entrinya](https://docs.didit.me/id/management-api/lists/delete-entry.md): wajah tersebut tidak lagi dicocokkan dengan sesi baru. ## OpenAPI ````yaml id/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 Verifikasi Identitas. Lakukan autentikasi dengan header x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/lists/{list_uuid}/entries/face-upload/: post: tags: - Lists summary: Unggah wajah ke daftar description: >- Menambahkan wajah ke daftar blokir wajah atau daftar izin wajah dari gambar JPEG atau PNG berenkode base64, ketika Anda tidak memiliki sesi verifikasi untuk dijadikan referensi. Didit mendeteksi wajah dalam gambar, menggunakan wajah terbesar, dan membuat entri yang nilai `value` dan `reference_object_uuid`-nya adalah UUID wajah baru tersebut. Wajah yang masuk daftar blokir menolak sesi baru yang wajahnya cocok; wajah yang masuk daftar izin melewati tindakan duplikasi wajah dan tidak pernah mengesampingkan kecocokan daftar blokir. Dalam aplikasi sandbox, gambar tidak dianalisis dan entri tersebut tidak mencocokkan apa pun. Kunci API dengan cakupan memerlukan `workflows: write`. Untuk mendaftarkan wajah dari sesi yang ada, gunakan [Buat entri daftar](https://docs.didit.me/id/management-api/lists/create-entry) dengan `reference_session_id` sebagai gantinya. operationId: upload_list_entry_face parameters: - name: list_uuid in: path required: true description: >- UUID dari daftar dengan `entry_type: face` dan `list_type: blocklist` atau `allowlist`. 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: >- JPEG atau PNG yang di-encode Base64, maksimal 2 MB setelah didecode, menampilkan wajah yang terlihat jelas. Kirim string base64 mentah, tanpa awalan `data:image/...;base64,`. comment: type: string default: '' description: Catatan teks bebas opsional, seperti alasan pencantuman. examples: Face image: value: image: /9j/4AAQSkZJRgABAQAAAQABAAD... comment: Known fraud attempt responses: '201': description: Entri wajah telah dibuat. 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: >- Daftar tidak menerima unggahan wajah, atau gambar tidak ada, tidak valid, terlalu besar, atau tidak menampilkan wajah yang dapat digunakan. Tidak ada entri yang dibuat. 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: >- Kunci API dengan cakupan terbatas telah kedaluwarsa. Kegagalan autentikasi lainnya mengembalikan `403`. content: application/json: examples: Expired API key: value: detail: This API key has expired. '403': description: >- Header `x-api-key` tidak ada (kunci yang salah, dicabut, atau kedaluwarsa menghasilkan `401`), atau kunci API dengan cakupan tertentu tidak memiliki `workflows: write` atau digunakan dari alamat IP di luar daftar izinnya. 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: >- Tidak ada daftar dengan UUID ini di aplikasi milik kunci API, atau daftar tersebut telah dihapus. content: application/json: examples: Not found: value: detail: List not found. '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: >- Analisis wajah tidak tersedia untuk sementara. Tidak ada entri yang dibuat; coba lagi nanti. 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: Satu nilai dalam sebuah daftar. 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: >- Pengidentifikasi entri. Gunakan sebagai `entry_uuid` dalam operasi Hapus entri daftar. value: type: string description: >- Nilai yang terdaftar: nomor telepon dalam format E.164, alamat email, nomor dokumen, alamat IP atau rentang CIDR, sidik jari perangkat, alamat dompet, rekening bank, kode negara ISO 3166-1 alpha-3, `vendor_data`, string apa pun pada daftar `key`, atau UUID wajah yang disimpan pada daftar wajah. Nilai yang Anda kirim disimpan dalam huruf kecil, kecuali nomor telepon dan kode negara. Pencocokan tidak membedakan huruf besar dan kecil. display_label: type: string nullable: true maxLength: 512 description: >- Label yang mudah dibaca manusia. Didit mengisinya untuk entri yang diambil dari sesi (misalnya nama pemegang dan nomor dokumen) saat Anda tidak mengirimkannya. comment: type: string description: Catatan teks bebas. String kosong jika tidak diatur. added_by: type: string nullable: true description: >- Pihak yang menambahkan entri: `api` (kunci API), alamat email pengguna konsol atau `console`, `system` atau `migration` (entri yang dibuat Didit), atau `rule` (tindakan aturan transaksi atau aturan pemantauan). reference_session_id: type: string format: uuid nullable: true description: >- Sesi verifikasi tempat entri tersebut diambil. `null` jika entri ditambahkan berdasarkan nilai. reference_session_number: type: integer nullable: true description: >- Nomor sesi tersebut dalam cakupan aplikasi, seperti yang ditampilkan di konsol. reference_session_type: type: string nullable: true enum: - kyc - kyb - null description: >- `kyc` untuk sesi verifikasi perorangan, `kyb` untuk sesi verifikasi bisnis, `null` ketika tidak ada sesi. reference_object_uuid: type: string format: uuid nullable: true description: >- Rekaman yang diwakili oleh entri: rekaman wajah, dokumen, telepon, atau email yang dibaca dari sesi, wajah yang dibuat melalui Unggah wajah ke daftar, atau UUID yang Anda kirim (misalnya UUID transaksi atau `didit_internal_id` milik pengguna). metadata: type: object nullable: true additionalProperties: true description: >- Konteks tambahan. Berisi kunci yang ditetapkan Didit (tercantum di sini) yang digabungkan dengan `metadata` apa pun yang Anda kirimkan saat membuat entri, dikembalikan seperti yang disimpan. `null` jika tidak ada. properties: reference_image_url: type: string description: >- Entri wajah: URL bertanda tangan berumur pendek, diterbitkan kembali pada setiap panggilan; `null` untuk kunci API dengan cakupan terbatas tanpa `media: read`. Tidak ada jika tidak ada gambar milik entri tersebut. front_image_url: type: string description: >- Entri dokumen yang memuat gambar depan dokumen: URL bertanda tangan berumur pendek, diterbitkan ulang pada setiap panggilan; `null` untuk kunci API dengan cakupan tanpa `media: read`. full_name: type: string description: 'Entri dokumen yang diambil dari sesi: nama lengkap pemegang.' issuing_state: type: string description: >- Entri dokumen yang diambil dari sesi: negara penerbit ISO 3166-1 alpha-3. document_type: type: string description: >- Entri dokumen yang diambil dari sesi: kode jenis dokumen, misalnya `P`, `ID` atau `DL`. region: type: string description: >- Entri dokumen yang diambil dari sesi: negara bagian atau provinsi penerbit dokumen yang diterbitkan secara regional, kosong jika tidak berlaku. Tidak diatur oleh penambahan item sesi ke daftar blokir. document_number: type: string description: 'Entri dokumen yang diambil dari sesi: nomor dokumen.' face_image_source: type: string enum: - front_image_camera_front - back_image_camera_front description: >- Entri wajah yang diambil dari swafoto pengambilan dokumen: swafoto yang mana. Tidak ada untuk wajah dari liveness. reference_node_id: type: string nullable: true description: >- Entri wajah yang diambil dari swafoto dari pengambilan dokumen: node verifikasi identitas asal swafoto tersebut. fingerprint_tier: type: string nullable: true enum: - persistent_id - composite_hash - legacy_fp - unknown - null description: >- Entri sidik jari perangkat yang diambil dari sesi: bagaimana sidik jari tersebut diturunkan. `persistent_id` mengidentifikasi satu perangkat; `composite_hash` dan `legacy_fp` dapat digunakan bersama oleh perangkat dari model yang sama. sandbox: type: boolean description: >- `true` pada entri wajah yang diunggah dalam aplikasi sandbox; entri tersebut tidak mencocokkan apa pun. reference_type: type: string enum: - transaction - vendor_user - vendor_business description: >- Ditetapkan oleh Anda: apa yang ditunjuk oleh `reference_object_uuid`, sehingga konsol menautkan kembali ke sana. reference_id: type: string description: 'Ditetapkan oleh Anda: pengidentifikasi rekaman sumber.' created_at: type: string format: date-time description: Waktu ketika entri ditambahkan. responses: RateLimitedWrite: description: >- Batas tulis bersama sebesar 300 permintaan per menit per kunci API telah terlampaui. Patuhi `Retry-After` sebelum mencoba lagi. 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: >- Kunci API aplikasi Anda, dari Developers -> API keys di Business Console. Kunci utama memiliki akses penuh. Kunci bernama dapat diberi cakupan: none, read, atau write per sumber daya, dibatasi pada beberapa alur kerja atau pada sesi yang disetujui, pada daftar alamat IP, dan pada tanggal kedaluwarsa. 401 berarti kuncinya salah, dicabut, atau kedaluwarsa; 403 berarti tidak ada kunci yang dikirimkan, kunci tidak memiliki akses ke sumber daya atau tindakan ini, atau permintaan datang dari alamat di luar daftar IP-nya; 404 pada rute sesi berarti sesi berada di luar alur kerja atau status kunci tersebut. Kunci tanpa akses media menerima URL gambar, video, dan PDF sebagai null, dan kunci tanpa izin tulis sesi menerima tautan sesi dan token sebagai null. Lihat https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.