> ## 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: listas biométricas

> Envie um rosto em base64 para uma lista de bloqueio ou permissão facial da Didit, que extrai a biometria e a usa em futuras comparações faciais.



Prompt da API para enviar rosto a uma lista
        Copiar o prompt para a área de transferência



      
      

\<pre>

\`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://<media-host>/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.`

\</pre>



      
      

Colar em

Envie uma imagem de rosto codificada em base64 para uma lista de bloqueio ou lista de permissão de rostos. A Didit detecta os rostos na imagem, mantém o maior deles, armazena a imagem e um recorte desse rosto e calcula o template biométrico facial com o qual as novas sessões são comparadas. O `value` da nova entrada é o UUID desse rosto.Disponível apenas para listas com `entry_type: face` e `list_type: blocklist` ou `list_type: allowlist`.> [!TIP]
>
> Se você está adicionando um rosto à lista de bloqueio ou à lista de permissão **a partir de uma sessão existente**, use [Criar entrada](https://docs.didit.me/pt-br/management-api/lists/create-entry.md) com `reference_session_id`: assim, a entrada fica vinculada à sessão.> [!WARNING]
>
> A imagem deve conter um rosto claramente visível e ter no máximo 2 MB depois de decodificada. Se nenhum rosto for detectado, a requisição retorna `400` e nenhuma entrada é criada. Se a análise facial estiver temporariamente indisponível, a requisição retorna `503`: tente novamente mais tarde.Para remover o rosto da lista, [exclua a entrada correspondente](https://docs.didit.me/pt-br/management-api/lists/delete-entry.md): ela deixa de gerar correspondências com novas sessões.


## OpenAPI

````yaml pt-br/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 de verificação de identidade. Autentique-se com o cabeçalho x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/lists/{list_uuid}/entries/face-upload/:
    post:
      tags:
        - Lists
      summary: Enviar um rosto para uma lista
      description: >-
        Adiciona um rosto a uma lista de bloqueio de rostos ou a uma lista de
        permissão de rostos a partir de uma imagem JPEG ou PNG codificada em
        base64, para quando você não tem uma sessão de verificação para
        referenciar. A Didit detecta os rostos na imagem, usa o maior e cria uma
        entrada cujos `value` e `reference_object_uuid` são o UUID do novo
        rosto. Um rosto na lista de bloqueio recusa novas sessões cujo rosto
        corresponda; um rosto na lista de permissão ignora a ação de rosto
        duplicado e nunca se sobrepõe a uma correspondência na lista de
        bloqueio. Em uma aplicação de sandbox, a imagem não é analisada e a
        entrada não corresponde a nada. Uma chave de API com escopo precisa de
        `workflows: write`. Para incluir na lista um rosto de uma sessão
        existente, use [Criar uma entrada de
        lista](https://docs.didit.me/pt-br/management-api/lists/create-entry)
        com `reference_session_id`.
      operationId: upload_list_entry_face
      parameters:
        - name: list_uuid
          in: path
          required: true
          description: >-
            UUID de uma lista com `entry_type: face` e `list_type: blocklist` ou
            `allowlist`.
          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: >-
                    JPEG ou PNG codificado em Base64, com no máximo 2 MB após a
                    decodificação, mostrando um rosto claramente visível. Envie
                    a string base64 pura, sem o prefixo
                    `data:image/...;base64,`.
                comment:
                  type: string
                  default: ''
                  description: >-
                    Nota opcional em texto livre, como o motivo da inclusão na
                    lista.
            examples:
              Face image:
                value:
                  image: /9j/4AAQSkZJRgABAQAAAQABAAD...
                  comment: Known fraud attempt
      responses:
        '201':
          description: A entrada de rosto foi criada.
          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: >-
            A lista não aceita envio de rostos, ou a imagem está ausente, é
            inválida, grande demais ou não mostra um rosto utilizável. Nenhuma
            entrada foi criada.
          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: >-
            A chave de API com escopo expirou. Outras falhas de autenticação
            retornam `403`.
          content:
            application/json:
              examples:
                Expired API key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            O cabeçalho `x-api-key` está ausente (uma chave incorreta, revogada
            ou expirada recebe `401`), ou uma chave de API com escopo não tem
            `workflows: write` ou é usada a partir de um endereço IP fora da sua
            lista de permissões.
          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: >-
            Não existe nenhuma lista com este UUID na aplicação da chave de API,
            ou ela foi excluída.
          content:
            application/json:
              examples:
                Not found:
                  value:
                    detail: List not found.
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
        '503':
          description: >-
            A análise facial está temporariamente indisponível. Nenhuma entrada
            foi criada; tente novamente mais tarde.
          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: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->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: Um valor em uma lista.
      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: >-
            Identificador da entrada. Use-o como `entry_uuid` em Excluir uma
            entrada da lista.
        value:
          type: string
          description: >-
            O valor listado: um número de telefone em E.164, um endereço de
            e-mail, um número de documento, um endereço IP ou intervalo CIDR,
            uma impressão digital de dispositivo, um endereço de carteira, uma
            conta bancária, um código de país ISO 3166-1 alpha-3, um
            `vendor_data`, qualquer string em uma lista `key` ou o UUID do rosto
            armazenado em uma lista de rostos. Os valores que você envia são
            armazenados em letras minúsculas, exceto números de telefone e
            códigos de país. A correspondência não diferencia maiúsculas de
            minúsculas.
        display_label:
          type: string
          nullable: true
          maxLength: 512
          description: >-
            Rótulo legível. A Didit o preenche para entradas obtidas de uma
            sessão (por exemplo, o nome do titular e o número do documento)
            quando você não envia nenhum.
        comment:
          type: string
          description: Nota em texto livre. String vazia quando não definida.
        added_by:
          type: string
          nullable: true
          description: >-
            Quem adicionou a entrada: `api` (uma chave de API), o e-mail de um
            usuário do console ou `console`, `system` ou `migration` (entradas
            criadas pela Didit), ou `rule` (uma ação de regra de transação ou de
            monitoramento).
        reference_session_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Sessão de verificação da qual a entrada foi obtida. `null` quando a
            entrada foi adicionada por valor.
        reference_session_number:
          type: integer
          nullable: true
          description: Número dessa sessão no escopo da aplicação, como exibido no console.
        reference_session_type:
          type: string
          nullable: true
          enum:
            - kyc
            - kyb
            - null
          description: >-
            `kyc` para uma sessão de verificação de pessoa, `kyb` para uma
            sessão de verificação de empresa, `null` quando não há sessão.
        reference_object_uuid:
          type: string
          format: uuid
          nullable: true
          description: >-
            O registro que a entrada representa: o registro de rosto, documento,
            telefone ou e-mail lido de uma sessão, o rosto criado por Enviar um
            rosto para uma lista ou o UUID que você enviou (por exemplo, um UUID
            de transação ou o `didit_internal_id` de um usuário).
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Contexto adicional. Contém as chaves definidas pela Didit (listadas
            aqui) mescladas com qualquer `metadata` que você enviou ao criar a
            entrada, retornadas como foram armazenadas. `null` quando não há
            nenhum.
          properties:
            reference_image_url:
              type: string
              description: >-
                Entradas de rosto: URL assinada de curta duração, emitida
                novamente a cada chamada; `null` para uma chave de API com
                escopo sem `media: read`. Ausente quando nenhuma imagem pertence
                à entrada.
            front_image_url:
              type: string
              description: >-
                Entradas de documento que têm uma imagem da frente do documento:
                URL assinada de curta duração, emitida novamente a cada chamada;
                `null` para uma chave de API com escopo sem `media: read`.
            full_name:
              type: string
              description: >-
                Entradas de documento obtidas de uma sessão: nome completo do
                titular.
            issuing_state:
              type: string
              description: >-
                Entradas de documento obtidas de uma sessão: país emissor no
                formato ISO 3166-1 alpha-3.
            document_type:
              type: string
              description: >-
                Entradas de documento obtidas de uma sessão: código do tipo de
                documento, por exemplo `P`, `ID` ou `DL`.
            region:
              type: string
              description: >-
                Entradas de documento obtidas de uma sessão: estado ou província
                emissora de um documento emitido regionalmente, vazio quando não
                se aplica. Não é definido por Adicionar itens da sessão à lista
                de bloqueio.
            document_number:
              type: string
              description: >-
                Entradas de documento obtidas de uma sessão: o número do
                documento.
            face_image_source:
              type: string
              enum:
                - front_image_camera_front
                - back_image_camera_front
              description: >-
                Entradas de rosto obtidas de uma selfie de captura de documento:
                qual selfie. Ausente para rostos de prova de vida.
            reference_node_id:
              type: string
              nullable: true
              description: >-
                Entradas de rosto obtidas de uma selfie de captura de documento:
                o nó de Verificação de identidade de onde a selfie veio.
            fingerprint_tier:
              type: string
              nullable: true
              enum:
                - persistent_id
                - composite_hash
                - legacy_fp
                - unknown
                - null
              description: >-
                Entradas de impressão digital do dispositivo obtidas de uma
                sessão: como a impressão digital foi derivada. `persistent_id`
                identifica um único dispositivo; `composite_hash` e `legacy_fp`
                podem ser compartilhados por dispositivos do mesmo modelo.
            sandbox:
              type: boolean
              description: >-
                `true` em uma entrada facial enviada em uma aplicação de
                sandbox; essa entrada não corresponde a nada.
            reference_type:
              type: string
              enum:
                - transaction
                - vendor_user
                - vendor_business
              description: >-
                Definido por você: aquilo para o qual `reference_object_uuid`
                aponta, para que o console crie um link de volta para ele.
            reference_id:
              type: string
              description: 'Definido por você: identificador do registro de origem.'
        created_at:
          type: string
          format: date-time
          description: Quando a entrada foi adicionada.
  responses:
    RateLimitedWrite:
      description: >-
        O limite compartilhado de escrita de 300 requisições por minuto por
        chave de API foi excedido. Respeite `Retry-After` antes de tentar
        novamente.
      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: >-
        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.