> ## 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. # Carregar rosto de utilizador: API e perfil do fornecedor > Carregue uma imagem facial em base64 para um perfil de utilizador existente na Didit, após criar ou importar o utilizador com vendor_data. Prompt para carregar o rosto do utilizador Copiar o prompt para a área de transferência \

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

\
Colar em ## Visão geralUtilize este endpoint quando importar utilizadores de outro fornecedor e já tiver uma imagem de rosto fiável para cada pessoa. O utilizador continua identificado pelo seu `vendor_data`, mas este endpoint para anexar o perfil usa `didit_internal_id` para que o utilizador de destino seja inequívoco.> [!NOTE] > > Isto é diferente de [Carregar rosto para a lista](https://docs.didit.me/pt/management-api/lists/upload-face.md). O carregamento do perfil anexa um rosto a um utilizador para efeitos de prova, deteção de duplicados e pesquisa facial. O carregamento para lista acrescenta um rosto a uma lista de bloqueio de rostos, para que as sessões de correspondência futuras possam ser recusadas.## Endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## Fluxo de migração**1. Criar ou encontrar o utilizador**Chame [`POST /v3/users/create/`](https://docs.didit.me/pt/management-api/users/create) para um perfil novo, ou [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/pt/management-api/users/get) para um perfil existente.**2. Guardar didit\_internal\_id**A resposta do utilizador inclui `didit_internal_id`. Continue a usar `vendor_data` na sua base de dados; use `didit_internal_id` apenas nos endpoints de anexação de perfil.**3. Carregar o rosto**Envie uma imagem em base64 sem prefixo no campo `image`. O back-end valida a descodificação da imagem, o tamanho da imagem e a deteção de rosto antes de a guardar.## Exemplo```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" }' ```## Corpo do pedido| Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `image` | string | Sim | JPG ou PNG em base64 sem prefixo. Não inclua `data:image/...;base64,`. Tamanho máximo após descodificação: 2 MB. | | `comment` | string | Não | Nota visível para o operador no perfil do utilizador. |## 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" } ```## Validação e limites- Máximo de 5 rostos carregados manualmente por utilizador. - O tamanho máximo da imagem após descodificação é de 2 MB. - A imagem tem de estar em base64 válido e ser descodificada como uma imagem. - A imagem tem de conter um rosto detetável. Sempre que possível, use um recorte frontal e bem iluminado do rosto. - O rosto carregado fica indexado para deteção futura de duplicados e pesquisa facial. - O rosto carregado não é adicionado automaticamente à lista de bloqueio.## Listar ou eliminar rostos carregadosPara listar os rostos do 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" ```Para eliminar um rosto do 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" ```## PermissõesUtilize uma chave de API da mesma aplicação. A chave tem de pertencer a uma aplicação autorizada a gerir o perfil do utilizador de destino.## Modos de falha- `400`: base64 inválido, imagem inválida, nenhum rosto detetável, imagem com mais de 2 MB ou o utilizador já tem 5 rostos carregados. - `401`: credenciais em falta ou inválidas. - `403`: a chave de API é válida, mas não tem permissão para gerir este perfil de utilizador. - `404`: não existe nenhum utilizador com esse `didit_internal_id` na aplicação. - `429`: limite de pedidos atingido; aguarde e tente novamente, usando `Retry-After`.## Relacionados- [Criar utilizador](https://docs.didit.me/pt/management-api/users/create.md) - [Obter utilizador](https://docs.didit.me/pt/management-api/users/get.md) - [Importar e exportar utilizadores](https://docs.didit.me/pt/entities/users/import-export.md) - [Rostos e biometria](https://docs.didit.me/pt/entities/users/faces-and-biometrics.md) - [Carregar rosto para a lista de bloqueio](https://docs.didit.me/pt/management-api/lists/upload-face.md) ## OpenAPI ````yaml pt/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 Verificação de identidade. Autentique-se com o cabeçalho 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: Carregar rosto do utilizador description: >- Anexe uma imagem facial fidedigna importada a um perfil de Utilizador existente. Utilize isto após criar ou recuperar um Utilizador por `vendor_data` e ler o seu `didit_internal_id`. O rosto carregado é guardado no perfil do Utilizador e indexado para deteção de duplicados e pesquisa facial. Não é adicionado a uma lista de bloqueio de rostos. operationId: upload_user_face parameters: - name: organization_id in: path required: true schema: type: string format: uuid description: UUID da organização à qual pertence a aplicação. - name: application_id in: path required: true schema: type: string format: uuid description: UUID da aplicação que detém o perfil de Utilizador. - name: didit_internal_id in: path required: true schema: type: string format: uuid description: >- UUID interno de utilizador da Didit, devolvido como `didit_internal_id` por `GET /v3/users/{vendor_data}/` e `POST /v3/users/create/`. requestBody: required: true content: application/json: schema: type: object required: - image properties: image: type: string format: byte description: >- Imagem facial em bruto codificada em base64 (JPG ou PNG). Não inclua o prefixo `data:image/...;base64,`. Tamanho máximo descodificado: 2 MB. comment: type: string description: >- Nota opcional, visível para o operador, sobre o rosto carregado. default: '' examples: Imported face: summary: Anexar um rosto importado de um fornecedor anterior value: image: /9j/4AAQSkZJRgABAQEA... comment: Imported from previous KYC provider responses: '201': description: Rosto carregado e associado ao perfil do Utilizador. content: application/json: schema: type: object required: - uuid - image_url - comment - uploaded_by - created_at properties: uuid: type: string format: uuid description: UUID do registo facial de utilizador carregado. image_url: type: string format: uri nullable: true description: URL assinado para a imagem de rosto carregada. comment: type: string nullable: true description: Comentário fornecido quando o rosto foi carregado. uploaded_by: type: string nullable: true description: >- E-mail ou identificador do ator que fez o carregamento, quando disponível. created_at: type: string format: date-time description: Carimbo de data/hora do carregamento. 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: >- Corpo do pedido ou imagem inválidos. Causas comuns: base64 inválido, imagem inválida, nenhum rosto detetável, imagem com mais de 2 MB, embedding em falta ou o utilizador já tem 5 rostos carregados. 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: Chave de API em falta ou inválida. content: application/json: examples: Missing key: value: detail: Authentication credentials were not provided. '403': description: >- A credencial é válida, mas não permite escrever perfis de utilizador para esta aplicação. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: >- Não existe nenhum utilizador para esse `didit_internal_id` na aplicação. content: application/json: examples: Not found: value: detail: Not found. '429': description: Limite de pedidos excedido; reduza a frequência e tente novamente. 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: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.