> ## 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. # Pesquisa facial API: deduplicação 1:N e redes de fraude > Didit: pesquisa facial 1:N para utilizadores verificados. Deteta duplicados e redes de fraude. Inferência sub-2s, paga por chamada. ## OpenAPI ````yaml pt/openapi-25.json POST /v3/face-search/ 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/face-search/: post: tags: - Standalone APIs summary: Pesquisa facial description: >- Pesquise uma imagem de rosto (1:N) no índice de pesquisa facial da sua aplicação — rostos registados a partir de sessões de verificação, chamadas de API autónomas guardadas, carregamentos diretos de rostos de perfis de utilizador e as suas listas de bloqueio/permissão — e obtenha correspondências de similaridade classificadas, além de avisos de lista de bloqueio e duplicados. **Como funciona.** O maior rosto detetado em `user_image` tem o seu embedding gerado e é pesquisado no índice, circunscrito à sua aplicação. São devolvidas até **5 correspondências** acima do limiar de similaridade em `matches`, cada uma com `similarity_percentage`, a sessão de origem (`session_id`, `session_number`, `status`, `vendor_data`), os `user_details` extraídos durante a verificação de documentos dessa sessão, os sinalizadores `is_blocklisted` / `is_allowlisted` e um discriminador `source` (`session`, `imported` ou `list_entry`). - `search_type=most_similar` (predefinição) classifica todos os rostos registados por similaridade — utilize-o para desduplicação e investigação de redes de fraude. - `search_type=blocklisted_or_approved` restringe os candidatos a rostos em listas de bloqueio, rostos em listas de permissão, rostos de sessões aprovadas e rostos de perfis de utilizador importados, classificando primeiro as entradas da lista de bloqueio — utilize-o quando o objetivo principal for a triagem em listas de bloqueio. O `status` é `Declined` apenas quando é acionado um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST`; `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) e `MULTIPLE_FACES_DETECTED` (`warning`) nunca recusam. Ao contrário da Prova de vida passiva, este endpoint **não** exclui da correspondência sessões anteriores com os mesmos `vendor_data`. Uma análise de prova de vida passiva também é executada internamente e armazenada com a sessão persistida, mas o seu resultado não faz parte desta resposta. **Faturação.** Cada resposta `200` consome um crédito da API de Pesquisa facial (pago a partir do crédito do seu plano ou do saldo carregado). Um saldo insuficiente devolve `403` antes de qualquer processamento de imagem. **Persistência da sessão e registo facial (`save_api_request`, predefinição `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` através do `request_id` devolvido, webhook `status.updated`) e o rosto pesquisado é registado no seu índice de pesquisa facial. Os rostos registados por chamadas de Pesquisa facial são excluídos de resultados futuros da Pesquisa facial, para que pesquisas repetidas nunca correspondam entre si. Quando `false`, a chamada é pontual: nada é armazenado, o rosto não é registado e os valores de `match_image_url` são caminhos de armazenamento interno em vez de URLs para transferência. **Sandbox.** As chaves de API de sandbox ignoram todo o processamento e faturação: após a validação do pedido (dados de entrada com formato incorreto continuam a devolver `400`), o endpoint devolve um payload simulado estático `Approved`, nenhuma sessão é persistida e nenhum crédito é consumido. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais em falta ou inválidas devolvem `403` (`{"detail": "You do not have permission to perform this action."}`) — esta API nunca devolve `401`. **Limite de pedidos.** Limite partilhado de 300 pedidos de escrita por minuto, por chave de API em todos os endpoints POST/PATCH/DELETE; excedê-lo devolve `429`. operationId: post_v3face-search parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Imagem facial frontal para efetuar a pesquisa. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de carregamento: **5 MB** (ficheiros maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para ~0.5 MB antes do processamento, pelo que resoluções muito altas não melhoram a precisão. A imagem deve conter pelo menos um rosto detetável — caso contrário, o endpoint devolve `400`. Quando vários rostos estão presentes, o maior é pesquisado e um aviso `MULTIPLE_FACES_DETECTED` é adicionado. search_type: type: string default: most_similar enum: - most_similar - blocklisted_or_approved description: >- Política de pesquisa. `most_similar` (predefinição) classifica cada rosto registado na sua aplicação por similaridade. `blocklisted_or_approved` restringe os candidatos a rostos em lista de bloqueio, rostos em lista de permissões, rostos de sessões aprovadas e rostos importados de perfis de utilizador — com as entradas na lista de bloqueio classificadas primeiro. example: most_similar rotate_image: type: boolean default: false description: >- Quando `true`, o serviço tenta rotações de 90 graus da entrada e utiliza a orientação que produzir a melhor deteção facial. Útil quando a orientação EXIF está ausente. Adiciona latência. example: false save_api_request: type: boolean default: true description: >- Quando `true` (padrão), persiste a chamada como uma sessão do tipo API, emite um webhook `status.updated`, pré-assina os valores de `match_image_url` e regista o rosto pesquisado no seu índice de Pesquisa facial (os registos de Pesquisa facial são excluídos de pesquisas futuras). Quando `false`, a pesquisa é de execução única — nenhuma sessão é armazenada e o rosto não é registado. example: true vendor_data: type: string description: >- Identificador opaco opcional (o seu ID de utilizador, e-mail, UUID...) guardado na sessão persistida e devolvido. Não exclui rostos do mesmo utilizador dos resultados de pesquisa. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido. Em pedidos multipart, envie-o como um campo de texto codificado em JSON — é convertido num objeto. example: flow: dedup_check example: user_image: (binary JPEG/PNG selfie) search_type: most_similar rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: dedup_check responses: '200': description: >- Pesquisa facial concluída. `face_search.matches` contém até 5 rostos semelhantes ordenados por semelhança; uma matriz vazia significa que nenhum rosto registado excedeu o limiar mínimo de semelhança. `status` é `Declined` apenas em correspondências na lista de bloqueio — correspondências duplicadas por si só devolvem `Approved`, portanto inspecione `matches` e `warnings`, não apenas `status`. Quando `save_api_request=true`, `request_id` é o id de sessão persistido. Cada correspondência contém `source` (`session`, `imported`, `list_entry` ou `retained_template`), `vendor_user_id` e `biometric_template_id`; uma correspondência `retained_template` provém de um template biométrico sem imagem mantido após a sessão de origem ter sido eliminada e tem os campos de sessão, `match_image_url` e `user_details` como `null`. content: application/json: examples: Blocklist hit (Declined): summary: O rosto coincide com um rosto na lista de bloqueio value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef face_search: status: Declined total_matches: 1 matches: - session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 session_number: 323442 similarity_percentage: 99.99 source: session vendor_data: user-1 verification_date: '2025-01-01T00:00:00Z' user_details: full_name: Jane Marie Doe document_type: ID document_number: X1234567 match_image_url: https:///face/3f6a1c2e/reference.jpg status: Approved is_blocklisted: true is_allowlisted: false api_service: null vendor_user_id: 2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f biometric_template_id: null user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 323442 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Duplicate found (Approved): summary: >- O rosto já apareceu noutra sessão aprovada — informativo, sem recusa value: request_id: 5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f face_search: status: Approved total_matches: 1 matches: - session_id: 1f2e3d4c-5b6a-7980-1122-334455667788 session_number: 1024 similarity_percentage: 87.42 source: session vendor_data: user-9 verification_date: '2025-11-20T09:15:00Z' user_details: null match_image_url: https:///face/9c8b7a6d/reference.jpg status: Approved is_blocklisted: false is_allowlisted: false api_service: PASSIVE_LIVENESS vendor_user_id: 2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f biometric_template_id: null user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: - risk: DUPLICATED_FACE feature: LIVENESS additional_data: duplicated_session_id: 1f2e3d4c-5b6a-7980-1122-334455667788 duplicated_session_number: 1024 api_service: PASSIVE_LIVENESS log_type: information short_description: Duplicated face from other approved session long_description: >- The system identified a duplicated face from another approved session, requiring further investigation. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' No matches (Approved): summary: >- Nenhum rosto registado ultrapassou o limiar mínimo de similaridade value: request_id: 9d8c7b6a-5f4e-3d2c-1b0a-998877665544 face_search: status: Approved total_matches: 0 matches: [] user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório. face_search: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined` apenas quando for acionado um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST`. As correspondências duplicadas e os avisos de múltiplos rostos nunca causam uma recusa. total_matches: type: integer description: Número de entradas em `matches` (0–5). example: 1 matches: type: array maxItems: 5 description: >- Até 5 rostos do seu índice de pesquisa facial que excedem o limiar de similaridade, ordenados por similaridade (com entradas na lista de bloqueio classificadas primeiro quando `search_type=blocklisted_or_approved`). Vazio quando nenhum rosto registado for suficientemente semelhante. items: type: object properties: session_id: type: string format: uuid nullable: true description: >- ID da sessão de verificação à qual pertence a face correspondente. `null` quando `source` é `imported`, `list_entry` ou `retained_template`. example: 882c42d5-8a4d-4d20-8080-a22f57822c86 session_number: type: integer nullable: true description: >- Número de sessão legível apresentado na Business Console. `null` para correspondências que não sejam de sessão. example: 323442 similarity_percentage: type: number format: float minimum: 0 maximum: 100 description: >- Semelhança entre o rosto submetido e o rosto correspondente (0–100). example: 99.99 source: type: string enum: - session - imported - list_entry - retained_template description: >- Onde o rosto correspondente foi registado: `session` — uma sessão de verificação ou uma chamada de API autónoma guardada; `imported` — um rosto carregado diretamente para um perfil de Utilizador; `list_entry` — um rosto associado a uma das suas listas; `retained_template` — um template biométrico sem imagem armazenado num Utilizador, listado em `/v3/biometric-templates/`. vendor_data: type: string nullable: true description: >- `vendor_data` da sessão correspondente ou utilizador associado para rostos importados e com modelo retido. example: user-1 vendor_user_id: type: string format: uuid nullable: true description: >- ID do utilizador vinculado. `null` para entradas de lista e correspondências de sessão sem utilizador. example: 2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4 biometric_template_id: type: string format: uuid nullable: true description: >- ID do template biométrico retido. Definido apenas quando `source` é `retained_template`; `null` caso contrário. example: null verification_date: type: string format: date-time nullable: true description: >- Quando o rosto correspondente foi originalmente capturado ou quando um modelo retido foi criado (`YYYY-MM-DDThh:mm:ssZ`). `null` para correspondências de `list_entry`. example: '2025-01-01T00:00:00Z' user_details: type: object nullable: true description: >- Dados de identidade extraídos durante a verificação de documentos da sessão correspondente. `null` quando a sessão correspondente não tem dados de documentos (p. ex., sessões apenas com prova de vida) e sempre `null` para correspondências com `retained_template`. Para correspondências com `source: imported`, é preenchido a partir do perfil de Utilizador: `full_name` definido, `document_type`/`document_number` nulos. properties: full_name: type: string nullable: true example: Jane Marie Doe document_type: type: string nullable: true example: ID document_number: type: string nullable: true example: X1234567 match_image_url: type: string nullable: true description: >- URL com limite temporal (`https:///...`) da imagem de referência do rosto correspondente quando `save_api_request=true`. Com `save_api_request=false`, este é um caminho de armazenamento interno que não pode ser descarregado diretamente. Sempre `null` para correspondências de `retained_template`, pois os modelos retidos não contêm qualquer imagem. example: https:///face/3f6a1c2e/reference.jpg status: type: string nullable: true description: >- Estado da sessão correspondente (`Approved`, `Declined`, `In Review`, …). `null` para correspondências `imported`/`list_entry`. example: Approved is_blocklisted: type: boolean description: >- `true` quando o rosto correspondente está na sua lista de bloqueio facial. Qualquer correspondência na lista de bloqueio suficientemente semelhante recusa a pesquisa. is_allowlisted: type: boolean description: >- `true` quando o rosto correspondente está numa das suas listas de permissões. As correspondências em listas de permissões suprimem avisos de duplicados. api_service: type: string nullable: true description: >- Definido quando a face correspondente foi registada através de uma chamada de API autónoma (ex.: `PASSIVE_LIVENESS`); `null` para sessões de verificação normais e faces importadas. example: null user_image: type: object description: >- Resultados da deteção facial para a imagem submetida. As entradas aqui contêm apenas `bbox` e `confidence`. properties: entities: type: array description: >- Uma entrada por rosto detetado. O maior rosto é o pesquisado. items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Caixa delimitadora `[x_min, y_min, x_max, y_max]` em píxeis. example: - 40 - 40 - 120 - 120 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança da deteção facial (0–1). example: 0.732973 best_angle: type: integer description: >- Rotação (graus) que produziu a melhor deteção facial; diferente de zero apenas quando `rotate_image=true` corrigiu a orientação. Nunca é null neste endpoint (assume 0 por predefinição quando o modelo a omite). example: 0 warnings: type: array description: >- Sinais de risco. `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` (`error`) recusam a pesquisa; `MULTIPLE_FACES_DETECTED` (`warning`) e `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) são meramente indicativos. items: type: object properties: risk: type: string enum: - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: Código de risco legível por máquina. feature: type: string enum: - LIVENESS description: >- Funcionalidade que gerou o aviso. Sempre `LIVENESS` neste endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- `null` para `MULTIPLE_FACES_DETECTED`. As correspondências na lista de bloqueio contêm `{blocklisted_session_id, blocklisted_session_number, api_service}`; as correspondências duplicadas contêm `{duplicated_session_id, duplicated_session_number, api_service}` a apontar para a primeira sessão correspondente. log_type: type: string enum: - error - warning - information description: >- Gravidade. Os avisos `error` alteram o `status` para `Declined`; as entradas `warning` e `information` são informativas e nunca recusam por si sós. short_description: type: string description: >- Resumo de uma linha legível por humanos sobre o risco. long_description: type: string description: Explicação legível do risco. vendor_data: type: string nullable: true description: Eco do `vendor_data` que enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que enviou, ou `null`. created_at: type: string format: date-time description: >- Carimbo de data/hora ISO 8601 (UTC) de quando a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Erro de validação. Devolvido quando `user_image` está em falta, excede 5 MB, tem uma extensão não suportada ou quando **nenhum rosto é detetado** na imagem enviada. Os erros de campo utilizam o envelope `{field: [messages]}` do DRF; as falhas de deteção facial utilizam `{"error": ...}`. content: application/json: examples: No face detected: summary: >- A imagem descodifica-se corretamente, mas não contém nenhum rosto detetável value: error: No face detected in the image Missing image: summary: '`user_image` não incluído nos dados do formulário' value: user_image: - No file was submitted. Unsupported file extension: summary: Extensão de ficheiro fora de tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: O carregamento excede o limite de 5 MB value: user_image: - File size should not exceed 5 MB '403': description: >- Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{"error": ...}` antes de qualquer processamento de imagens ocorrer. content: application/json: examples: Missing or invalid API key: summary: Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 pedidos de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-search/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'search_type=most_similar' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_search.search( user_image=open("user_image.jpg", "rb"), search_type="most_similar", rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "dedup_check"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceSearch.search({ user_image: await fileFromPath("user_image.jpg"), search_type: "most_similar", rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "dedup_check" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceSearch.Search(ctx, didit.FaceSearchSearchParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tSearchType: didit.Some(didit.FaceSearchSearchParamsSearchType(\"most_similar\")),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"dedup_check\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceSearchSearchParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceSearch().search(FaceSearchSearchParams.builder() .userImage(Path.of("user_image.jpg")) .searchType(FaceSearchSearchParams.SearchType.of("most_similar")) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "dedup_check")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceSearch->search([ 'user_image' => File::fromPath('user_image.jpg'), 'search_type' => 'most_similar', 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'dedup_check'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_search.search( user_image: Pathname("user_image.jpg"), search_type: "most_similar", rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "dedup_check" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceSearch.SearchAsync(new FaceSearchSearchParams { UserImage = FileUpload.FromPath("user_image.jpg"), SearchType = new FaceSearchSearchParamsSearchType("most_similar"), RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "dedup_check" }, }); 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.