> ## 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 Pengguna: Profil Pengguna Vendor > Unggah gambar wajah base64 ke profil pengguna Didit yang sudah ada setelah membuat atau mengimpor pengguna dengan vendor_data. Prompt Unggah Wajah Pengguna Salin prompt ke papan klip \

\`Goal: Attach a trusted imported face image to an existing Didit User profile.

Use case: I am migrating users from another provider. I already have a stable vendor_data and a face image I am allowed to process. I want the User profile to carry that face for evidence, duplicate detection, and face search.

Flow:
1\. Create or retrieve the User by vendor_data:
POST https://verification.didit.me/v3/users/create/
GET  https://verification.didit.me/v3/users/{vendor_data}/
2\. Read didit_internal_id from the User response.
3\. Upload the face to:
POST https://verification.didit.me/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

Auth: x-api-key for the same application.
Content-Type: application/json

Request body:
\- image (string, required) — raw base64-encoded JPG or PNG. Do not include a data URL prefix. Max decoded size: 2 MB.
\- comment (string, optional) — operator-visible note, for example "Imported from previous KYC provider".

Response 201:
\{
"uuid": "face-upload-uuid",
"image_url": "https://signed-url.example/...",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}

Limits:
\- Max 5 manually uploaded faces per User.
\- The image must decode as an image and contain a detectable face.
\- This enrolls the face for profile evidence and matching. It does not add the face to a blocklist.

To block a face, use POST /v3/lists/{list_uuid}/entries/face-upload/ with a face-type list instead.`

\
Tempel ke ## IkhtisarGunakan endpoint ini saat Anda mengimpor Pengguna dari penyedia lain dan sudah memiliki gambar wajah tepercaya untuk setiap orang. Pengguna tetap diidentifikasi dengan `vendor_data` Anda, tetapi endpoint lampiran profil ini menggunakan `didit_internal_id` agar Pengguna sasaran tidak ambigu.> [!NOTE] > > Ini berbeda dari [Unggah wajah ke daftar](https://docs.didit.me/id/management-api/lists/upload-face.md). Unggahan profil melampirkan wajah ke Pengguna sebagai bukti, untuk deteksi duplikat, dan untuk pencarian wajah. Unggahan ke daftar menambahkan wajah ke daftar blokir jenis wajah sehingga sesi pencocokan di masa mendatang dapat ditolak.## Endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## Alur migrasi**1. Buat atau temukan Pengguna**Panggil [`POST /v3/users/create/`](https://docs.didit.me/id/management-api/users/create) untuk profil baru, atau [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/id/management-api/users/get) untuk profil yang sudah ada.**2. Simpan didit\_internal\_id**Respons Pengguna menyertakan `didit_internal_id`. Tetap gunakan `vendor_data` di database Anda; gunakan `didit_internal_id` hanya untuk endpoint lampiran profil.**3. Unggah wajah**Kirim gambar base64 mentah di kolom `image`. Backend memvalidasi dekode gambar, ukuran gambar, dan deteksi wajah sebelum menyimpannya.## Contoh```bash theme={null} # 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": "", "comment": "Imported from previous KYC provider" }' ```## Isi permintaan| Kolom | Tipe | Wajib | Deskripsi | | - | - | - | - | | `image` | string | Ya | JPG atau PNG yang dikodekan base64 secara mentah. Jangan sertakan `data:image/...;base64,`. Ukuran maksimum setelah didekode: 2 MB. | | `comment` | string | Tidak | Catatan yang terlihat oleh operator dan ditampilkan pada profil Pengguna. |## Respons```json theme={null} { "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" } ```## Validasi dan batasan- Maksimum 5 wajah yang diunggah secara manual per Pengguna. - Ukuran gambar maksimum setelah didekode adalah 2 MB. - Gambar harus berupa base64 yang valid dan dapat didekode sebagai gambar. - Gambar harus berisi wajah yang dapat dideteksi. Gunakan potongan wajah dari depan dengan pencahayaan yang baik jika memungkinkan. - Wajah yang diunggah diindeks untuk deteksi duplikat dan pencarian wajah di masa mendatang. - Wajah yang diunggah tidak otomatis masuk ke daftar blokir.## Menampilkan atau menghapus wajah yang diunggahMenampilkan daftar wajah profil:```bash theme={null} 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" ```Menghapus satu wajah profil:```bash theme={null} 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" ```## IzinGunakan kunci API untuk aplikasi yang sama. Kunci harus milik aplikasi yang diizinkan untuk mengelola profil Pengguna sasaran.## Mode kegagalan- `400`: base64 tidak valid, gambar tidak valid, tidak ada wajah yang dapat dideteksi, gambar melebihi 2 MB, atau Pengguna sudah memiliki 5 wajah yang diunggah. - `401`: kredensial tidak ada atau tidak valid. - `403`: kunci API valid tetapi tidak diizinkan untuk mengelola profil Pengguna ini. - `404`: tidak ada Pengguna dengan `didit_internal_id` tersebut dalam aplikasi. - `429`: terkena batas laju; lakukan jeda berdasarkan `Retry-After`.## Terkait- [Buat Pengguna](https://docs.didit.me/id/management-api/users/create.md) - [Ambil Pengguna](https://docs.didit.me/id/management-api/users/get.md) - [Impor dan Ekspor Pengguna](https://docs.didit.me/id/entities/users/import-export.md) - [Wajah dan Biometrik](https://docs.didit.me/id/entities/users/faces-and-biometrics.md) - [Unggah wajah ke daftar blokir](https://docs.didit.me/id/management-api/lists/upload-face.md) ## OpenAPI ````yaml id/openapi-25.json POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/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/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/: post: tags: - Users summary: Unggah wajah pengguna description: >- Lampirkan gambar wajah tepercaya yang diimpor ke profil Pengguna yang ada. Gunakan ini setelah membuat atau mengambil Pengguna berdasarkan `vendor_data` dan membaca `didit_internal_id`-nya. Wajah yang diunggah disimpan di profil Pengguna dan diindeks untuk deteksi duplikat serta pencarian wajah. Wajah tersebut tidak ditambahkan ke daftar blokir wajah. operationId: upload_user_face parameters: - name: organization_id in: path required: true schema: type: string format: uuid description: UUID organisasi yang memiliki aplikasi. - name: application_id in: path required: true schema: type: string format: uuid description: UUID aplikasi yang memiliki profil Pengguna. - name: didit_internal_id in: path required: true schema: type: string format: uuid description: >- UUID Pengguna internal Didit, dikembalikan sebagai `didit_internal_id` oleh `GET /v3/users/{vendor_data}/` dan `POST /v3/users/create/`. requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- Gambar wajah mentah JPG atau PNG berenkode base64. Jangan sertakan awalan `data:image/...;base64,`. Ukuran maksimum setelah didekode: 2 MB. comment: type: string description: >- Catatan opsional yang dapat dilihat operator untuk wajah yang diunggah. default: '' examples: Imported face: summary: Lampirkan wajah yang diimpor dari penyedia sebelumnya value: image: /9j/4AAQSkZJRgABAQEA... comment: Imported from previous KYC provider responses: '201': description: Wajah diunggah dan dilampirkan ke profil Pengguna. content: application/json: schema: type: object required: - uuid - image_url - comment - uploaded_by - created_at properties: uuid: type: string format: uuid description: UUID rekaman wajah Pengguna yang diunggah. image_url: type: string format: uri nullable: true description: URL bertanda tangan untuk gambar wajah yang diunggah. comment: type: string nullable: true description: Komentar yang diberikan saat wajah diunggah. uploaded_by: type: string nullable: true description: >- Email atau pengidentifikasi aktor pengunggah jika tersedia. created_at: type: string format: date-time description: Stempel waktu unggahan. examples: Uploaded: value: 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' '400': description: >- Body permintaan atau gambar tidak valid. Penyebab umum: base64 tidak valid, gambar tidak valid, tidak ada wajah yang terdeteksi, gambar lebih dari 2 MB, embedding hilang, atau Pengguna sudah memiliki 5 wajah yang diunggah. content: application/json: examples: No face: value: image: >- No face detected in the image. Please upload a clear photo with a visible face. Too many faces: value: detail: Maximum of 5 faces per user reached. Too large: value: image: Image exceeds maximum size of 2 MB. '401': description: Kunci API tidak ada atau tidak valid. content: application/json: examples: Missing key: value: detail: Authentication credentials were not provided. '403': description: >- Kredensial valid tetapi tidak dapat menulis profil Pengguna untuk aplikasi ini. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: >- Tidak ada Pengguna untuk `didit_internal_id` tersebut dalam aplikasi. content: application/json: examples: Not found: value: detail: Not found. '429': description: Batas laju terlampaui; lakukan back off dan coba lagi. content: application/json: examples: Rate limited: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- 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"}' - lang: python label: Python source: |- 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) - lang: javascript label: Node.js source: >- 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); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\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.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); - lang: php label: PHP source: >- users->uploadFace('11111111-2222-3333-4444-555555555555', [ 'image' => '/9j/4AAQSkZJRgABAQEA...', 'comment' => 'Imported from previous KYC provider', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- 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_h - lang: csharp label: .NET source: >- using 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)); components: 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.