> ## 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 de upload de rosto do usuário: perfil com vendor_data > Envie uma imagem facial em base64 para um perfil de usuário existente no Didit após criar ou importar o usuário com vendor_data. Prompt para enviar o rosto do usuário 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 geralUse este endpoint quando você importar usuários de outro provedor e já tiver uma imagem facial confiável de cada pessoa. O usuário continua identificado pelo seu `vendor_data`, mas este endpoint de anexo ao perfil usa `didit_internal_id` para que o usuário de destino seja inequívoco.> [!NOTE] > > Isso é diferente de [Enviar rosto para uma lista](https://docs.didit.me/pt-br/management-api/lists/upload-face.md). O envio ao perfil anexa um rosto a um usuário para fins de evidência, detecção de duplicatas e busca facial. O envio à lista adiciona um rosto a uma lista de bloqueio de faces para que futuras sessões de correspondência 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. Crie ou localize o usuário**Chame [`POST /v3/users/create/`](https://docs.didit.me/pt-br/management-api/users/create) para um novo perfil ou [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/pt-br/management-api/users/get) para um perfil existente.**2. Armazene o didit\_internal\_id**A resposta do usuário inclui `didit_internal_id`. Continue usando `vendor_data` no seu banco de dados; use `didit_internal_id` apenas nos endpoints de associação de perfil.**3. Envie o rosto**Envie uma imagem em base64 puro no campo `image`. O backend valida a decodificação da imagem, o tamanho da imagem e a detecção de rosto antes de salvá-la.## 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 da requisição| Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | `image` | string | Sim | JPG ou PNG codificado em base64 puro. Não inclua `data:image/...;base64,`. Tamanho máximo após decodificação: 2 MB. | | `comment` | string | Não | Nota visível para operadores, exibida no perfil do usuário. |## 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 enviados manualmente por usuário. - O tamanho máximo da imagem após decodificação é de 2 MB. - A imagem deve estar em base64 válido e ser decodificada como imagem. - A imagem deve conter um rosto detectável. Sempre que possível, use um recorte frontal e bem iluminado do rosto. - O rosto enviado é indexado para futuras detecções de duplicatas e buscas faciais. - O rosto enviado não é adicionado automaticamente a uma lista de bloqueio.## Listar ou excluir rostos enviadosListe 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" ```Exclua 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õesUse uma chave de API da mesma aplicação. A chave deve pertencer a uma aplicação autorizada a gerenciar o perfil do usuário de destino.## Modos de falha- `400`: base64 inválido, imagem inválida, nenhum rosto detectável, imagem acima de 2 MB ou o usuário já tem 5 rostos enviados. - `401`: credenciais ausentes ou inválidas. - `403`: a chave de API é válida, mas não tem permissão para gerenciar este perfil de usuário. - `404`: não existe usuário com esse `didit_internal_id` na aplicação. - `429`: limite de requisições atingido; aguarde antes de tentar novamente, conforme `Retry-After`.## Conteúdo relacionado- [Criar usuário](https://docs.didit.me/pt-br/management-api/users/create.md) - [Obter usuário](https://docs.didit.me/pt-br/management-api/users/get.md) - [Importar e exportar usuários](https://docs.didit.me/pt-br/entities/users/import-export.md) - [Rostos e biometria](https://docs.didit.me/pt-br/entities/users/faces-and-biometrics.md) - [Enviar rosto para a lista de bloqueio](https://docs.didit.me/pt-br/management-api/lists/upload-face.md) ## OpenAPI ````yaml pt-br/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: Enviar rosto do usuário description: >- Anexe uma imagem facial importada e confiável a um perfil de User existente. Use isto depois de criar ou obter um User por `vendor_data` e ler o seu `didit_internal_id`. O rosto enviado é armazenado no perfil do User e indexado para detecção de duplicatas e busca facial. Ele não é adicionado a uma lista de bloqueio facial. operationId: upload_user_face parameters: - name: organization_id in: path required: true schema: type: string format: uuid description: UUID da organização proprietária da aplicação. - name: application_id in: path required: true schema: type: string format: uuid description: UUID da aplicação à qual o perfil do Usuário pertence. - name: didit_internal_id in: path required: true schema: type: string format: uuid description: >- UUID interno do usuário na Didit, retornado 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 bruta em JPG ou PNG codificada em base64. Não inclua o prefixo `data:image/...;base64,`. Tamanho máximo decodificado: 2 MB. comment: type: string description: Nota opcional visível para o operador sobre o rosto enviado. default: '' examples: Imported face: summary: Anexar um rosto importado de um provedor anterior value: image: /9j/4AAQSkZJRgABAQEA... comment: Imported from previous KYC provider responses: '201': description: Rosto enviado e vinculado ao perfil do usuário. content: application/json: schema: type: object required: - uuid - image_url - comment - uploaded_by - created_at properties: uuid: type: string format: uuid description: UUID do registro facial de usuário enviado. image_url: type: string format: uri nullable: true description: URL assinada da imagem de rosto enviada. comment: type: string nullable: true description: Comentário fornecido quando o rosto foi enviado. uploaded_by: type: string nullable: true description: >- E-mail ou identificador do ator que fez o upload, quando disponível. created_at: type: string format: date-time description: Data e hora do upload. 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 da requisição ou imagem inválidos. Causas comuns: base64 inválido, imagem inválida, nenhum rosto detectável, imagem com mais de 2 MB, embedding ausente ou o usuário já tem 5 rostos enviados. 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 ausente 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 pode gravar perfis de usuário 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 usuário com esse `didit_internal_id` na aplicação. content: application/json: examples: Not found: value: detail: Not found. '429': description: Limite de requisições excedido; aguarde 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: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, 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á errada, 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 a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.