> ## 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 busca facial: deduplicação 1:N e redes de fraude > Busca facial 1:N da Didit: POST /v3/face-search/ detecta duplicatas, redes de fraude e reautenticação. Inferência em menos de 2s, pague por uso. ## OpenAPI ````yaml pt-br/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: Busca facial description: >- Pesquise uma imagem de rosto (1:N) no índice de busca facial da sua aplicação — rostos cadastrados a partir de sessões de verificação, chamadas avulsas à API que foram salvas, envios diretos de rostos para perfis de usuário e suas listas de bloqueio/permissão — e receba correspondências de similaridade ordenadas, além de avisos de lista de bloqueio e de duplicidade. **Como funciona.** O maior rosto detectado em `user_image` é convertido em embedding e pesquisado no índice, restrito à sua aplicação. Até **5 correspondências** acima do limite mínimo de similaridade são retornadas 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 documento dessa sessão, as flags `is_blocklisted` / `is_allowlisted` e um discriminador `source` (`session`, `imported` ou `list_entry`). - `search_type=most_similar` (padrão) ordena todos os rostos cadastrados por similaridade — use-o para deduplicação e investigação de redes de fraude. - `search_type=blocklisted_or_approved` restringe os candidatos a rostos na lista de bloqueio, rostos na lista de permissão, rostos de sessões aprovadas e rostos importados de perfis de usuário, ordenando primeiro as entradas da lista de bloqueio — use-o quando o objetivo principal for a triagem na lista de bloqueio. `status` é `Declined` somente quando um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST` é disparado; `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) e `MULTIPLE_FACES_DETECTED` (`warning`) nunca causam recusa. Diferentemente da Prova de vida passiva, este endpoint **não** exclui da correspondência sessões anteriores com o mesmo `vendor_data`. Uma análise de prova de vida passiva também é executada internamente e armazenada com a sessão persistida, mas seu resultado não faz parte desta resposta. **Faturamento.** Cada resposta `200` consome um crédito da API de Busca facial (pago com o crédito do seu plano ou com o saldo de recarga). Saldo insuficiente retorna `403` antes de qualquer processamento de imagem. **Persistência da sessão e cadastro do rosto (`save_api_request`, padrão `true`).** Quando `true`, a chamada é persistida como uma sessão do tipo API (Business Console, `GET /v3/session/{sessionId}/decision/` por meio do `request_id` retornado, webhook `status.updated`) e o rosto pesquisado é cadastrado no seu índice de busca facial. Rostos cadastrados por chamadas de Busca facial são excluídos dos resultados futuros da Busca facial, de modo que pesquisas repetidas nunca correspondem entre si. Quando `false`, a chamada é avulsa: nada é armazenado, o rosto não é cadastrado e os valores de `match_image_url` são caminhos de armazenamento internos, e não URLs para download. **Sandbox.** Chaves de API de sandbox ignoram todo o processamento e o faturamento: após a validação da requisição (entradas malformadas ainda retornam `400`), o endpoint retorna 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 ausentes ou inválidas retornam `403` (`{"detail": "You do not have permission to perform this action."}`) — esta API nunca retorna `401`. **Limite de requisições.** Cota de escrita compartilhada de 300 requisições/min por chave de API em todos os endpoints POST/PATCH/DELETE; ao excedê-la, a API retorna `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 frontal do rosto a ser usada na busca. Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de upload: **5 MB** (arquivos maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para ~0,5 MB antes do processamento, portanto resoluções muito altas não melhoram a precisão. A imagem deve conter pelo menos um rosto detectável; caso contrário, o endpoint retorna `400`. Quando há vários rostos, a busca é feita pelo maior e um aviso `MULTIPLE_FACES_DETECTED` é adicionado. search_type: type: string default: most_similar enum: - most_similar - blocklisted_or_approved description: >- Política de busca. `most_similar` (padrão) classifica todos os rostos cadastrados na sua aplicação por similaridade. `blocklisted_or_approved` restringe os candidatos a rostos da lista de bloqueio, rostos da lista de permissões, rostos de sessões aprovadas e rostos importados de perfis de usuário — com as entradas da lista de bloqueio classificadas primeiro. example: most_similar rotate_image: type: boolean default: false description: >- Quando `true`, o serviço testa rotações de 90 graus da entrada e usa a orientação que produz a melhor detecção de rosto. Útil quando a orientação EXIF está ausente. Aumenta a 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`, gera URLs pré-assinadas para os valores de `match_image_url` e cadastra o rosto pesquisado no seu índice de busca facial (os cadastros da Busca facial são excluídos de buscas futuras). Quando `false`, a busca é avulsa: nenhuma sessão é armazenada e o rosto não é cadastrado. example: true vendor_data: type: string description: >- Identificador opaco opcional (seu ID de usuário, e-mail, UUID…) armazenado na sessão persistida e devolvido. Ele não exclui rostos do mesmo usuário dos resultados da busca. 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 requisições multipart, envie-o como um campo de string codificada em JSON, que é convertido em um 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: >- Busca facial concluída. `face_search.matches` contém até 5 rostos semelhantes ordenados por similaridade; um array vazio significa que nenhum rosto cadastrado ultrapassou o limite mínimo de similaridade. `status` é `Declined` apenas em ocorrências na lista de bloqueio: correspondências duplicadas por si só retornam `Approved`, portanto verifique `matches` e `warnings`, não apenas `status`. Quando `save_api_request=true`, `request_id` é o ID da sessão persistida. Cada correspondência traz `source` (`session`, `imported`, `list_entry` ou `retained_template`), `vendor_user_id` e `biometric_template_id`; uma correspondência `retained_template` vem de um template biométrico sem imagem mantido após a exclusão da sessão de origem e tem campos de sessão, `match_image_url` e `user_details` como `null`. content: application/json: examples: Blocklist hit (Declined): summary: O rosto corresponde a um rosto da 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 em outra sessão aprovada — apenas 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: >- Nenhuma face cadastrada superou o limite 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` somente quando um aviso `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST` foi disparado. Correspondências duplicadas e avisos de múltiplos rostos nunca causam 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 busca facial que ultrapassam o limite mínimo de similaridade, ordenados por similaridade (com as entradas da lista de bloqueio classificadas primeiro quando `search_type=blocklisted_or_approved`). Vazio quando nenhum rosto cadastrado é suficientemente semelhante. items: type: object properties: session_id: type: string format: uuid nullable: true description: >- ID da sessão de verificação à qual pertence o rosto 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 de fácil leitura exibido no Business Console. `null` para correspondências que não são sessões. example: 323442 similarity_percentage: type: number format: float minimum: 0 maximum: 100 description: >- Similaridade entre o rosto enviado e o rosto correspondente (0–100). example: 99.99 source: type: string enum: - session - imported - list_entry - retained_template description: >- De onde o rosto correspondente foi cadastrado: `session`: uma sessão de verificação ou uma chamada avulsa à API salva; `imported`: um rosto enviado diretamente para um perfil de usuário; `list_entry`: um rosto vinculado a uma das suas listas; `retained_template`: um template biométrico sem imagem armazenado em um usuário, listado em `/v3/biometric-templates/`. vendor_data: type: string nullable: true description: >- `vendor_data` da sessão correspondente ou do User vinculado, para rostos importados e com template biométrico retido. example: user-1 vendor_user_id: type: string format: uuid nullable: true description: >- ID do User vinculado. `null` para entradas de lista e correspondências de sessão sem User. example: 2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4 biometric_template_id: type: string format: uuid nullable: true description: >- Id do template biométrico retido. Definido somente quando `source` é `retained_template`; caso contrário, `null`. example: null verification_date: type: string format: date-time nullable: true description: >- Quando o rosto correspondente foi capturado originalmente, ou quando um template retido foi criado (`YYYY-MM-DDThh:mm:ssZ`). `null` para correspondências `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 documento da sessão correspondente. `null` quando a sessão correspondente não tem dados de documento (por exemplo, sessões apenas de prova de vida) e sempre `null` para correspondências `retained_template`. Para correspondências `source: imported`, é preenchido a partir do perfil do usuário: `full_name` preenchido, `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 tempo limitado (`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 baixado diretamente. Sempre `null` para correspondências `retained_template`, porque os templates retidos não contêm imagem. example: https:///face/3f6a1c2e/reference.jpg status: type: string nullable: true description: >- Status 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 de rostos. Qualquer correspondência suficientemente semelhante na lista de bloqueio recusa a busca. is_allowlisted: type: boolean description: >- `true` quando o rosto correspondente está em uma das suas listas de permissão. Correspondências em listas de permissão suprimem os avisos de duplicidade. api_service: type: string nullable: true description: >- Preenchido quando o rosto correspondente foi cadastrado por uma chamada de API independente (por exemplo, `PASSIVE_LIVENESS`); `null` para sessões de verificação comuns e rostos importados. example: null user_image: type: object description: >- Resultados da detecção facial para a imagem enviada. Os itens aqui contêm apenas `bbox` e `confidence`. properties: entities: type: array description: >- Uma entrada por rosto detectado. O maior rosto é o usado na busca. 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 pixels. example: - 40 - 40 - 120 - 120 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança da detecção facial (0–1). example: 0.732973 best_angle: type: integer description: >- Rotação (em graus) que produziu a melhor detecção de rosto; diferente de zero apenas quando `rotate_image=true` corrigiu a orientação. Nunca é nula neste endpoint (o padrão é 0 quando o modelo a omite). example: 0 warnings: type: array description: >- Sinais de risco. `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` (`error`) recusam a busca. `MULTIPLE_FACES_DETECTED` (`warning`) e `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) são apenas informativos. 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: >- Recurso que emitiu o aviso. Sempre `LIVENESS` neste endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- `null` para `MULTIPLE_FACES_DETECTED`. Ocorrências na lista de bloqueio trazem `{blocklisted_session_id, blocklisted_session_number, api_service}`; ocorrências de duplicata trazem `{duplicated_session_id, duplicated_session_number, api_service}`, apontando para a primeira sessão correspondente. log_type: type: string enum: - error - warning - information description: >- Severidade. Avisos `error` levam o `status` para `Declined`; entradas `warning` e `information` são apenas informativas e nunca recusam a sessão por conta própria. short_description: type: string description: Resumo legível do risco em uma linha. long_description: type: string description: Explicação legível do risco. vendor_data: type: string nullable: true description: Eco do `vendor_data` que você enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que você enviou, ou `null`. created_at: type: string format: date-time description: >- Timestamp ISO 8601 (UTC) do momento em que a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Erro de validação. Retornado quando `user_image` está ausente, excede 5 MB ou tem uma extensão não suportada, ou quando **nenhum rosto é detectado** na imagem enviada. Erros de campo usam o envelope `{field: [messages]}` do DRF; falhas de detecção facial usam `{"error": ...}`. content: application/json: examples: No face detected: summary: >- A imagem é decodificada corretamente, mas não contém nenhum rosto detectá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 arquivo 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 upload excede o limite de 5 MB value: user_image: - File size should not exceed 5 MB '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente e também quando o saldo da organização que faz a chamada não cobre a chamada; uma chave incorreta, revogada ou expirada retorna `401`. Uma chave ausente retorna `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada retorna `401`. Créditos insuficientes retornam `403` com `{"error": ...}` antes de qualquer processamento da imagem. content: application/json: examples: Missing or invalid API key: summary: Nenhum 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 requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. 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 requisições 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: >- 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.