> ## 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 cerca facial 1:N: deduplicació i xarxes de frau

> Didit: POST /v3/face-search/ per a cerca facial 1:N d'usuaris verificats. Detecta duplicats i xarxes de frau. Inferència sub-2s, sense contractes.



## OpenAPI

````yaml ca/openapi-25.json POST /v3/face-search/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/face-search/:
    post:
      tags:
        - Standalone APIs
      summary: Cerca facial
      description: >-
        Cerca una imatge facial (1:N) a l'índex de cerca facial de la teva
        aplicació (cares registrades a partir de sessions de verificació, crides
        d'API independents desades, pujades directes de cares de perfils
        d'usuari i les teves llistes de bloqueig i de permesos) i rep
        coincidències de similitud ordenades juntament amb advertències de
        llista de bloqueig i duplicats.


        **Com funciona.** La cara més gran detectada a `user_image` es
        converteix en un embedding i es cerca a l'índex, limitat a la teva
        aplicació. Es retornen fins a **5 coincidències** per sobre del llindar
        mínim de similitud a `matches`, cadascuna amb `similarity_percentage`,
        la sessió d'origen (`session_id`, `session_number`, `status`,
        `vendor_data`), els `user_details` extrets durant la verificació de
        documents d'aquella sessió, els indicadors `is_blocklisted` /
        `is_allowlisted` i un discriminador de `source` (`session`, `imported` o
        `list_entry`).


        - `search_type=most_similar` (per defecte) classifica totes les cares
        registrades per similitud; utilitza'l per a la desduplicació i la
        investigació de xarxes de frau.

        - `search_type=blocklisted_or_approved` restringeix els candidats a
        cares a la llista de bloqueig, cares a la llista de permesos, cares de
        sessions aprovades i cares de perfils d'usuari importades, classificant
        primer les entrades a la llista de bloqueig; utilitza'l quan l'objectiu
        principal sigui el cribratge de llistes de bloqueig.


        `status` és `Declined` només quan s'activa una advertència
        `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`; `DUPLICATED_FACE` /
        `POSSIBLE_DUPLICATED_FACE` (`information`) i `MULTIPLE_FACES_DETECTED`
        (`warning`) mai rebutgen. A diferència de la prova de vida passiva,
        aquest endpoint **no** exclou de la coincidència les sessions anteriors
        amb el mateix `vendor_data`. També s'executa internament una anàlisi de
        prova de vida passiva que s'emmagatzema amb la sessió persistida, però
        el seu resultat no forma part d'aquesta resposta.


        **Facturació.** Cada resposta `200` consumeix un crèdit de l'API de
        cerca facial (descomptat del crèdit del teu pla o del saldo de
        recàrrega). Si el saldo és insuficient, es retorna un `403` abans de
        processar cap imatge.


        **Persistència de sessions i registre de cares (`save_api_request`, per
        defecte `true`).** Quan és `true`, la crida es persisteix com una sessió
        de tipus API (Business Console, `GET /v3/session/{sessionId}/decision/`
        mitjançant el `request_id` retornat, webhook `status.updated`) i la cara
        cercada es registra a l'índex de cerca facial. Les cares registrades
        mitjançant crides de cerca facial s'exclouen dels resultats futurs de
        cerca facial, de manera que les cerques repetides mai coincideixen entre
        si. Quan és `false`, la crida és d'un sol ús: no s'emmagatzema res, la
        cara no es registra i els valors de `match_image_url` són rutes
        d'emmagatzematge intern en comptes d'URL descarregables.


        **Sandbox.** Les claus d'API de sandbox ometen tot el processament i la
        facturació: després de validar la sol·licitud (les entrades amb format
        incorrecte continuen retornant `400`), l'endpoint retorna un payload
        simulat estàtic `Approved`, no es persisteix cap sessió i no es
        consumeixen crèdits.


        **Autenticació.** Envia la clau d'API de la teva aplicació a la
        capçalera `x-api-key`. Si les credencials falten o no són vàlides, es
        retorna un `403` (`{"detail": "You do not have permission to perform
        this action."}`); aquesta API mai retorna un `401`.


        **Límit de freqüència.** Límit compartit de 300 sol·licituds
        d'escriptura/min per clau d'API a tots els endpoints POST/PATCH/DELETE;
        si se supera, es retorna un `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: >-
                    Imatge frontal del rostre per fer la cerca. Extensions
                    permeses: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Mida màxima
                    de càrrega: **5 MB** (els fitxers més grans es rebutgen amb
                    `400`). Les imatges es comprimeixen automàticament a ~0.5 MB
                    abans de processar-les, de manera que una resolució gaire
                    alta no millora la precisió. La imatge ha de contenir
                    almenys una cara detectable; en cas contrari, l'endpoint
                    retorna `400`. Si hi ha diverses cares presents, es busca la
                    més gran i s'afegeix una advertència
                    `MULTIPLE_FACES_DETECTED`.
                search_type:
                  type: string
                  default: most_similar
                  enum:
                    - most_similar
                    - blocklisted_or_approved
                  description: >-
                    Política de cerca. `most_similar` (per defecte) classifica
                    cada cara registrada a la teva aplicació per similitud.
                    `blocklisted_or_approved` restringeix els candidats a cares
                    a la llista de bloqueig, cares a la llista blanca, cares de
                    sessions aprovades i cares de perfils d'usuari importats —
                    classificant les entrades a la llista de bloqueig en primer
                    lloc.
                  example: most_similar
                rotate_image:
                  type: boolean
                  default: false
                  description: >-
                    Quan és `true`, el servei prova rotacions de 90 graus de
                    l'entrada i utilitza l'orientació que ofereix la millor
                    detecció facial. Útil quan falta l'orientació EXIF. Afegeix
                    latència.
                  example: false
                save_api_request:
                  type: boolean
                  default: true
                  description: >-
                    Quan és `true` (per defecte), manté la crida com una sessió
                    de tipus API, emet un webhook `status.updated`, presigna els
                    valors de `match_image_url` i inscriu la cara cercada al teu
                    índex de cerca facial (les inscripcions de Cerca facial
                    s'exclouen de cerques futures). Quan és `false`, la cerca és
                    d'un sol ús: no s'emmagatzema cap sessió i la cara no
                    s'inscriu.
                  example: true
                vendor_data:
                  type: string
                  description: >-
                    Identificador opac opcional (el teu ID d'usuari, correu
                    electrònic, UUID…) desat a la sessió persistent i retornat a
                    la resposta. No exclou les cares del mateix usuari dels
                    resultats de cerca.
                  example: user-123
                metadata:
                  type: object
                  additionalProperties: true
                  description: >-
                    Objecte JSON opcional emmagatzemat amb la sessió (quan
                    `save_api_request=true`) i retornat. En sol·licituds
                    multipart, envia'l com a camp de cadena codificat en JSON;
                    s'analitza com un objecte.
                  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: >-
            Cerca facial completada. `face_search.matches` conté fins a 5 cares
            similars ordenades per similitud; una matriu buida vol dir que cap
            cara registrada ha superat el llindar mínim de similitud. `status`
            és `Declined` només per coincidències amb la llista de bloqueig —
            les coincidències duplicades per si soles retornen `Approved`, per
            tant inspecciona `matches` i `warnings`, no només `status`. Quan
            `save_api_request=true`, `request_id` és l'identificador de sessió
            persistit. Cada coincidència conté `source` (`session`, `imported`,
            `list_entry` o `retained_template`), `vendor_user_id` i
            `biometric_template_id`; una coincidència `retained_template` prové
            d'una plantilla biomètrica sense imatge conservada després que la
            sessió d'origen s'hagués suprimit i té `null` als camps de sessió,
            `match_image_url` i `user_details`.
          content:
            application/json:
              examples:
                Blocklist hit (Declined):
                  summary: La cara coincideix amb una cara de la llista de bloqueig
                  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://<media-host>/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: >-
                    La cara ja ha aparegut en una altra sessió aprovada —
                    informatiu, sense rebuig
                  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://<media-host>/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: Cap cara registrada ha superat el llindar mínim de similitud
                  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 de sessió persistida quan `save_api_request=true`
                      (utilitzable amb `GET /v3/session/{sessionId}/decision/`);
                      en cas contrari, un UUID de correlació transitori.
                  face_search:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - Approved
                          - Declined
                        description: >-
                          `Declined` només quan s'ha activat una advertència
                          `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`.
                          Les coincidències duplicades i les advertències de
                          múltiples cares mai no causen rebuig.
                      total_matches:
                        type: integer
                        description: Nombre d'entrades a `matches` (0–5).
                        example: 1
                      matches:
                        type: array
                        maxItems: 5
                        description: >-
                          Fins a 5 cares del teu índex de cerca facial que
                          superen el llindar mínim de similitud, ordenades per
                          similitud (amb les entrades a la llista de bloqueig
                          classificades primer quan
                          `search_type=blocklisted_or_approved`). Buit quan cap
                          cara registrada és prou similar.
                        items:
                          type: object
                          properties:
                            session_id:
                              type: string
                              format: uuid
                              nullable: true
                              description: >-
                                ID de la sessió de verificació a la qual pertany
                                la cara coincident. `null` quan `source` és
                                `imported`, `list_entry` o `retained_template`.
                              example: 882c42d5-8a4d-4d20-8080-a22f57822c86
                            session_number:
                              type: integer
                              nullable: true
                              description: >-
                                Número de sessió fàcil de llegir que es mostra a
                                la Business Console. `null` per a coincidències
                                que no són de sessió.
                              example: 323442
                            similarity_percentage:
                              type: number
                              format: float
                              minimum: 0
                              maximum: 100
                              description: >-
                                Similitud entre la cara enviada i la cara
                                coincident (0–100).
                              example: 99.99
                            source:
                              type: string
                              enum:
                                - session
                                - imported
                                - list_entry
                                - retained_template
                              description: >-
                                D'on prové la cara coincident: `session` — una
                                sessió de verificació o una crida d'API
                                independent desada; `imported` — una cara pujada
                                directament a un perfil d'usuari; `list_entry` —
                                una cara associada a una de les teves llistes;
                                `retained_template` — una plantilla biomètrica
                                sense imatge emmagatzemada en un usuari,
                                llistada a `/v3/biometric-templates/`.
                            vendor_data:
                              type: string
                              nullable: true
                              description: >-
                                `vendor_data` de la sessió coincident o de
                                l'usuari vinculat per a cares importades i de
                                plantilla retinguda.
                              example: user-1
                            vendor_user_id:
                              type: string
                              format: uuid
                              nullable: true
                              description: >-
                                Identificador d'User vinculat. `null` per a
                                entrades de llista i coincidències de sessió
                                sense un User.
                              example: 2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4
                            biometric_template_id:
                              type: string
                              format: uuid
                              nullable: true
                              description: >-
                                ID de la plantilla biomètrica conservada. Només
                                s'estableix quan `source` és
                                `retained_template`; `null` en cas contrari.
                              example: null
                            verification_date:
                              type: string
                              format: date-time
                              nullable: true
                              description: >-
                                Quan es va capturar originalment la cara
                                coincident, o quan es va crear una plantilla
                                conservada (`YYYY-MM-DDThh:mm:ssZ`). `null` per
                                a coincidències de `list_entry`.
                              example: '2025-01-01T00:00:00Z'
                            user_details:
                              type: object
                              nullable: true
                              description: >-
                                Dades d'identitat extretes durant la verificació
                                del document de la sessió coincident. `null`
                                quan la sessió coincident no té dades de
                                document (p. ex., sessions només amb prova de
                                vida) i sempre `null` per a coincidències de
                                `retained_template`. En el cas de coincidències
                                amb `source: imported`, s'emplena a partir del
                                perfil d'usuari: `full_name` establert,
                                `document_type`/`document_number` nuls.
                              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 de durada limitada
                                (`https://<media-host>/...`) de la imatge de
                                referència de la cara coincident quan
                                `save_api_request=true`. Amb
                                `save_api_request=false`, aquesta és una ruta
                                d'emmagatzematge intern que no es pot
                                descarregar directament. Sempre és `null` per a
                                coincidències de `retained_template` perquè les
                                plantilles retingudes no contenen cap imatge.
                              example: https://<media-host>/face/3f6a1c2e/reference.jpg
                            status:
                              type: string
                              nullable: true
                              description: >-
                                Estat de la sessió que coincideix (`Approved`,
                                `Declined`, `In Review`, …). `null` per a
                                coincidències `imported`/`list_entry`.
                              example: Approved
                            is_blocklisted:
                              type: boolean
                              description: >-
                                `true` quan la cara coincident és a la teva
                                llista de bloqueig facial. Qualsevol
                                coincidència prou similar a la llista de
                                bloqueig rebutja la cerca.
                            is_allowlisted:
                              type: boolean
                              description: >-
                                `true` quan la cara coincident és en una de les
                                teves llistes d'autorització. Les coincidències
                                a la llista d'autorització suprimeixen les
                                advertències de duplicats.
                            api_service:
                              type: string
                              nullable: true
                              description: >-
                                S'estableix quan la cara coincident es va
                                registrar mitjançant una crida d'API independent
                                (p. ex., `PASSIVE_LIVENESS`); `null` per a
                                sessions de verificació habituals i cares
                                importades.
                              example: null
                      user_image:
                        type: object
                        description: >-
                          Resultats de la detecció facial per a la imatge
                          enviada. Les entrades aquí només contenen `bbox` i
                          `confidence`.
                        properties:
                          entities:
                            type: array
                            description: >-
                              Una entrada per cara detectada. La cara més gran
                              és la que se cerca.
                            items:
                              type: object
                              properties:
                                bbox:
                                  type: array
                                  items:
                                    type: integer
                                  minItems: 4
                                  maxItems: 4
                                  description: >-
                                    Quadre delimitador `[x_min, y_min, x_max,
                                    y_max]` en píxels.
                                  example:
                                    - 40
                                    - 40
                                    - 120
                                    - 120
                                confidence:
                                  type: number
                                  format: float
                                  minimum: 0
                                  maximum: 1
                                  description: Confiança de la detecció facial (0–1).
                                  example: 0.732973
                          best_angle:
                            type: integer
                            description: >-
                              Rotació (graus) que ha produït la millor detecció
                              facial; diferent de zero només quan
                              `rotate_image=true` ha corregit l'orientació. Mai
                              no és null en aquest endpoint (per defecte és 0
                              quan el model l'omet).
                            example: 0
                      warnings:
                        type: array
                        description: >-
                          Senyals de risc. `FACE_IN_BLOCKLIST` /
                          `POSSIBLE_FACE_IN_BLOCKLIST` (`error`) rebutgen la
                          cerca; `MULTIPLE_FACES_DETECTED` (`warning`) i
                          `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`
                          (`information`) són informatius.
                        items:
                          type: object
                          properties:
                            risk:
                              type: string
                              enum:
                                - MULTIPLE_FACES_DETECTED
                                - FACE_IN_BLOCKLIST
                                - POSSIBLE_FACE_IN_BLOCKLIST
                                - DUPLICATED_FACE
                                - POSSIBLE_DUPLICATED_FACE
                              description: Codi de risc llegible per màquina.
                            feature:
                              type: string
                              enum:
                                - LIVENESS
                              description: >-
                                Funcionalitat que ha generat l'advertència.
                                Sempre `LIVENESS` en aquest endpoint.
                            additional_data:
                              type: object
                              nullable: true
                              additionalProperties: true
                              description: >-
                                `null` per a `MULTIPLE_FACES_DETECTED`. Les
                                coincidències amb la llista de bloqueig inclouen
                                `{blocklisted_session_id,
                                blocklisted_session_number, api_service}`; les
                                coincidències per duplicat inclouen
                                `{duplicated_session_id,
                                duplicated_session_number, api_service}` que
                                apunten a la primera sessió coincident.
                            log_type:
                              type: string
                              enum:
                                - error
                                - warning
                                - information
                              description: >-
                                Gravetat. Les advertències `error` canvien
                                `status` a `Declined`; les entrades `warning` i
                                `information` són consultives i mai no rebutgen
                                per si soles.
                            short_description:
                              type: string
                              description: >-
                                Resum d'una sola línia del risc, llegible per a
                                humans.
                            long_description:
                              type: string
                              description: Explicació fàcil de llegir del risc.
                  vendor_data:
                    type: string
                    nullable: true
                    description: Ressò de les `vendor_data` que has enviat, o `null`.
                  metadata:
                    type: object
                    nullable: true
                    additionalProperties: true
                    description: Ressò de l'objecte `metadata` que has enviat, o `null`.
                  created_at:
                    type: string
                    format: date-time
                    description: >-
                      Marca de temps ISO 8601 (UTC) de quan s'ha generat la
                      resposta, p. ex. `2026-06-12T01:04:42.763237+00:00`.
        '400':
          description: >-
            Error de validació. Es retorna quan falta `user_image`, supera els 5
            MB, té una extensió no admesa o quan **no es detecta cap cara** a la
            imatge enviada. Els errors de camp utilitzen l'embolcall `{field:
            [messages]}` de DRF; els errors de detecció facial utilitzen
            `{"error": ...}`.
          content:
            application/json:
              examples:
                No face detected:
                  summary: >-
                    La imatge es descodifica correctament però no conté cap cara
                    detectable
                  value:
                    error: No face detected in the image
                Missing image:
                  summary: '`user_image` no s''ha inclòs a les dades del formulari'
                  value:
                    user_image:
                      - No file was submitted.
                Unsupported file extension:
                  summary: Extensió de fitxer no permesa (només 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: La pujada supera el límit de 5 MB
                  value:
                    user_image:
                      - File size should not exceed 5 MB
        '403':
          description: >-
            Permís denegat. Es retorna quan falta la capçalera `x-api-key`, i
            també quan el saldo de l'organització que fa la crida no pot cobrir
            la crida; una clau incorrecta, revocada o caducada retorna `401`. Si
            falta la clau es retorna `403` amb `{"detail": ...}`; una clau
            incorrecta, revocada o caducada retorna `401`. La manca de crèdit
            retorna `403` amb `{"error": ...}` abans que es produeixi cap
            processament d'imatges.
          content:
            application/json:
              examples:
                Missing or invalid API key:
                  summary: >-
                    Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha
                    revocat
                  value:
                    detail: You do not have permission to perform this action.
                Not enough credits:
                  summary: El saldo de l'organització no pot cobrir la crida
                  value:
                    error: >-
                      You don't have enough credits to perform this request.
                      Please top up at https://business.didit.me
        '429':
          description: >-
            S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE
            comparteixen un pressupost de 300 sol·licituds d'escriptura per
            minut per clau d'API (la creació de transaccions i la ingesta
            d'esdeveniments tenen un pressupost independent de 600). La resposta
            inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`,
            `X-RateLimit-Reset` i `Retry-After`.
          content:
            application/json:
              examples:
                Write rate limit exceeded:
                  summary: Més de 300 sol·licituds d'escriptura en el minut actual
                  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: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;
            use Didit\File;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->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<string, object> { ["flow"] = "dedup_check" },
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        La clau d'API de la teva aplicació, des de Developers -> API keys a la
        Business Console. La clau primària té accés complet. Una clau amb nom
        pot tenir l'abast limitat: cap, lectura o escriptura per recurs,
        limitada a determinats fluxos de treball o a sessions aprovades, a una
        llista d'adreces IP i a una data de caducitat. 401 significa que la clau
        és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap
        clau, que la clau no té accés a aquest recurs o acció, o que la
        sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una
        ruta de sessió significa que la sessió està fora dels fluxos de treball
        o estats de la clau. Una clau sense accés a fitxers multimèdia rep els
        URL d'imatge, vídeo i PDF com a null, i una clau sense permís
        d'escriptura de sessions rep els enllaços de sessió i els tokens com a
        null. Consulta https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.