> ## 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: बायोमेट्रिक सूचियाँ > Didit की चेहरा ब्लॉकलिस्ट या allowlist में base64 छवि अपलोड करें। 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/hi/management-api/lists/create-entry.md) का उपयोग करें: एंट्री उस सत्र से लिंक हो जाती है।> [!WARNING] > > छवि में एक साफ़ दिखने वाला चेहरा होना चाहिए, और डिकोड होने के बाद उसका आकार अधिकतम 2 MB होना चाहिए। अगर कोई चेहरा नहीं मिलता, तो अनुरोध `400` लौटाता है और कोई एंट्री नहीं बनती। अगर चेहरे का विश्लेषण अस्थायी रूप से उपलब्ध नहीं है, तो यह `503` लौटाता है: बाद में पुनः प्रयास करें।चेहरे को सूची से हटाने के लिए, [उसकी एंट्री हटाएँ](https://docs.didit.me/hi/management-api/lists/delete-entry.md)। इसके बाद वह नए सत्रों से मेल नहीं खाएगा। ## OpenAPI ````yaml hi/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/hi/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, डीकोड होने के बाद अधिकतम 2 MB, जिसमें साफ़ तौर पर दिखाई देने वाला चेहरा हो। बिना किसी `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: सूची में एक मान। 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: >- अतिरिक्त संदर्भ। 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` एक डिवाइस की पहचान करता है; `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 से। प्राथमिक कुंजी के पास पूर्ण एक्सेस होता है। एक नामित कुंजी को स्कोप किया जा सकता है: प्रति संसाधन 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.