> ## 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 per pujar la cara d'usuari: perfil de proveïdor > Puja una imatge facial en base64 a un perfil d'usuari existent de Didit després de crear o importar l'usuari amb vendor_data. Prompt per pujar la cara de l'usuari Copia el prompt al porta-retalls \

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

\
Enganxa a ## Visió generalFes servir aquest endpoint quan importis usuaris d'un altre proveïdor i ja tinguis una imatge facial de confiança de cada persona. L'usuari continua identificat per `vendor_data`, però aquest endpoint d'adjunció de perfil utilitza `didit_internal_id` perquè l'usuari de destinació quedi identificat sense ambigüitat.> [!NOTE] > > Això és diferent de [Pujar cara a la llista](https://docs.didit.me/ca/management-api/lists/upload-face.md). La pujada de perfil adjunta una cara a un usuari com a prova, per detectar duplicats i fer cerques facials. La pujada a la llista afegeix una cara a una llista de bloqueig de tipus facial perquè les sessions de verificació posteriors amb coincidència puguin ser rebutjades.## Endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## Flux de migració**1. Crea o troba l'usuari**Crida [`POST /v3/users/create/`](https://docs.didit.me/ca/management-api/users/create) per a un perfil nou, o [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/ca/management-api/users/get) per a un perfil existent.**2. Desa didit\_internal\_id**La resposta de l'usuari inclou `didit_internal_id`. Continua fent servir `vendor_data` a la teva base de dades; fes servir `didit_internal_id` només per als endpoints d'adjunció de perfil.**3. Puja la cara**Envia una imatge base64 en brut al camp `image`. El backend valida la decodificació de la imatge, la mida de la imatge i la detecció de cara abans de desar-la.## Exemple```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" }' ```## Cos de la sol·licitud| Camp | Tipus | Obligatori | Descripció | | - | - | - | - | | `image` | string | Sí | Imatge JPG o PNG codificada en base64 en brut. No incloguis `data:image/...;base64,`. Mida màxima decodificada: 2 MB. | | `comment` | string | No | Nota visible per a l'operador al perfil de l'usuari. |## Resposta```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" } ```## Validació i límits- Màxim 5 cares pujades manualment per usuari. - La mida màxima de la imatge decodificada és de 2 MB. - La imatge ha de ser base64 vàlid i decodificar-se com a imatge. - La imatge ha de contenir una cara detectable. Quan sigui possible, fes servir un retall frontal i ben il·luminat de la cara. - La cara pujada s'indexa per a la detecció de duplicats i la cerca facial posteriors. - La cara pujada no s'afegeix automàticament a la llista de bloqueig.## Llistar o eliminar cares pujadesLlistar les cares del perfil:```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" ```Eliminar una cara del perfil:```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" ```## PermisosFes servir una clau d'API de la mateixa aplicació. La clau ha de pertànyer a una aplicació autoritzada a gestionar el perfil d'usuari de destinació.## Modes de fallada- `400`: base64 no vàlid, imatge no vàlida, cap cara detectable, imatge de més de 2 MB, o l'usuari ja té 5 cares pujades. - `401`: credencials absents o no vàlides. - `403`: la clau d'API és vàlida però no té permís per gestionar aquest perfil d'usuari. - `404`: no existeix cap usuari per a aquest `didit_internal_id` a l'aplicació. - `429`: límit de freqüència superat; espera el temps que indiqui `Retry-After`.## Relacionats- [Crear usuari](https://docs.didit.me/ca/management-api/users/create.md) - [Obtenir usuari](https://docs.didit.me/ca/management-api/users/get.md) - [Importar i exportar usuaris](https://docs.didit.me/ca/entities/users/import-export.md) - [Cares i biometria](https://docs.didit.me/ca/entities/users/faces-and-biometrics.md) - [Pujar cara a la llista de bloqueig](https://docs.didit.me/ca/management-api/lists/upload-face.md) ## OpenAPI ````yaml ca/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 de verificació d'identitat. Autentica't amb la capçalera 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: Puja la cara de l'usuari description: >- Adjunta una imatge facial importada de confiança a un perfil d'usuari existent. Utilitza-ho després de crear o recuperar un usuari mitjançant `vendor_data` i llegir el seu `didit_internal_id`. La cara pujada s'emmagatzema al perfil d'usuari i s'indexa per a la detecció de duplicats i la cerca facial. No s'afegeix a cap llista de bloqueig facial. operationId: upload_user_face parameters: - name: organization_id in: path required: true schema: type: string format: uuid description: UUID de l'organització propietària de l'aplicació. - name: application_id in: path required: true schema: type: string format: uuid description: UUID de l'aplicació propietària del perfil d'usuari. - name: didit_internal_id in: path required: true schema: type: string format: uuid description: >- UUID d'usuari intern de Didit, retornat com a `didit_internal_id` per `GET /v3/users/{vendor_data}/` i `POST /v3/users/create/`. requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- Imatge facial en brut en format JPG o PNG codificada en base64. No incloguis el prefix `data:image/...;base64,`. Mida màxima un cop descodificada: 2 MB. comment: type: string description: >- Nota opcional visible per a l'operador sobre la cara carregada. default: '' examples: Imported face: summary: Adjunta una cara importada d'un proveïdor anterior value: image: /9j/4AAQSkZJRgABAQEA... comment: Imported from previous KYC provider responses: '201': description: Cara carregada i adjuntada al perfil d'usuari. content: application/json: schema: type: object required: - uuid - image_url - comment - uploaded_by - created_at properties: uuid: type: string format: uuid description: UUID del registre facial d'usuari pujat. image_url: type: string format: uri nullable: true description: URL signada per a la imatge facial pujada. comment: type: string nullable: true description: Comentari proporcionat quan es va carregar la cara. uploaded_by: type: string nullable: true description: >- Correu electrònic o identificador d'actor de qui ha pujat el fitxer, quan estigui disponible. created_at: type: string format: date-time description: Marca de temps de la pujada. 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: >- Cos de la sol·licitud o imatge no vàlids. Causes comunes: base64 no vàlid, imatge no vàlida, cap cara detectable, imatge de més de 2 MB, embedding absent o l'usuari ja té 5 cares carregades. 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: Falta la clau d'API o no és vàlida. content: application/json: examples: Missing key: value: detail: Authentication credentials were not provided. '403': description: >- La credencial és vàlida però no pot escriure perfils d'usuari per a aquesta aplicació. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: >- No existeix cap usuari per a aquest `didit_internal_id` a l'aplicació. content: application/json: examples: Not found: value: detail: Not found. '429': description: >- S'ha superat el límit de freqüència; redueix el ritme de les sol·licituds i reintenta-ho. 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: >- La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.