> ## Documentation index
> Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt
> Use it to discover all available pages before exploring further.

# Find similar face events by embedding

> Find face events for an organization that are similar to a specified face embedding. The events are returned in reverse chronological order, with the latest events appearing first.

```http
POST https://api2.rhombussystems.com/api/faceRecognition/faceEvent/findSimilarFaceEventsByEmbedding
```

EU organizations send the same request to `https://api2.eu.rhombussystems.com`.

## Authentication and parameters

- `x-auth-apikey` (header, required): Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints).
- `Authorization` (header): instead of an API key, an OAuth access token (`Bearer <token>`) with the `read` scope.
- `x-auth-scheme` (header, string, default: `api-token`): Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer <token>` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters. One of: `api-token`, `api`, `api-oauth-token`, `federated-token`, `partner-api-token`, `partner-api`, `partner-api-oauth-token`.
- `x-auth-org` (header, string<RUUID>): Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`.

## Request body

Content type: `application/json`. Request object for finding face events similar to a face embedding with search filtering and pagination.

- `embedding` (object): Returns the generated embedding or null if the embedding could not be generated. If image contains multiple faces, only the first generated embedding is returned.
- `pageRequest` (object): Pagination request for retrieving policy alerts. Page size must be between 1 and 1000.
- `searchFilter` (object): Search filter for finding similar face events with similarity thresholds and confidence settings.

## Response 200

OK. Content type: `application/json`

- `faceEvents` (array<object> | null): List of face events similar to the specified face embedding
- `lastEvaluatedKey` (string | null): Pagination key for retrieving the next page of similar face events

## Errors

Also 400, 401, 403, 429, 500, 503 with the standard error body (`errorCode`, `errorMsg`): https://developer.rhombus.com/errors

## OpenAPI

````yaml
openapi: 3.0.1
info:
  title: Rhombus API
  version: "1.0"
servers:
  - description: Production Server
    url: https://api2.rhombussystems.com
security:
  - ApiKeyAuth: []
paths:
  /api/faceRecognition/faceEvent/findSimilarFaceEventsByEmbedding:
    post:
      description: Find face events for an organization that are similar to a specified face embedding. The events are returned in reverse chronological order, with the latest events appearing first.
      operationId: findSimilarFaceEventsByEmbedding
      parameters:
        - description: "Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer <token>` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters."
          example: api-token
          in: header
          name: x-auth-scheme
          required: false
          schema:
            default: api-token
            enum:
              - api-token
              - api
              - api-oauth-token
              - federated-token
              - partner-api-token
              - partner-api
              - partner-api-oauth-token
            type: string
        - description: "Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`."
          in: header
          name: x-auth-org
          required: false
          schema:
            format: RUUID
            maxLength: 22
            minLength: 22
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Facerecognition_faceevent_FindSimilarFaceEventsByEmbeddingWSRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Facerecognition_faceevent_FindSimilarFaceEventsByEmbeddingWSResponse"
          description: OK
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      security:
        - ApiKeyAuth: []
        - oauth2:
            - read
      summary: Find similar face events by embedding
      tags:
        - Face Recognition Event Webservice
components:
  schemas:
    Facerecognition_faceevent_FindSimilarFaceEventsByEmbeddingWSRequest:
      description: Request object for finding face events similar to a face embedding with search filtering and pagination.
      properties:
        embedding:
          $ref: "#/components/schemas/Embedding"
        pageRequest:
          $ref: "#/components/schemas/DynamoPageRequest"
        searchFilter:
          $ref: "#/components/schemas/Facerecognition_faceevent_ExternalFaceEventSimilaritySearchFilter"
      type: object
    Embedding:
      description: Returns the generated embedding or null if the embedding could not be generated. If image contains multiple faces, only the first generated embedding is returned.
      properties:
        embeddingComparisonType:
          nullable: true
          type: string
        embeddingConfidence:
          format: float
          nullable: true
          type: number
        embeddingEncodingType:
          $ref: "#/components/schemas/EmbeddingEncodingTypeEnum"
        encodedEmbedding:
          nullable: true
          type: string
      type: object
    EmbeddingEncodingTypeEnum:
      enum:
        - Q_8_24
        - IEEE_754
      type: string
    DynamoPageRequest:
      description: Pagination request for retrieving policy alerts. Page size must be between 1 and 1000.
      properties:
        lastEvaluatedKey:
          nullable: true
          type: string
        maxPageSize:
          format: int32
          nullable: true
          type: integer
      type: object
    Facerecognition_faceevent_ExternalFaceEventSimilaritySearchFilter:
      description: Search filter for finding similar face events with similarity thresholds and confidence settings.
      properties:
        deviceUuids:
          description: Optional filter by a set of devices.
          items:
            description: RUUID with optional appended facet information
            example: AAAAAAAAAAAAAAAAAAAAAA.v0
            format: DeviceFacetUuid
            nullable: true
            type: string
          nullable: true
          type: array
        embeddingConfidenceThreshold:
          description: Optional face embedding confidence threshold used to filter out face events with embeddingconfidence values less than the specified threshold. Valid range [0,1].
          format: float
          maximum: 1
          minimum: 0
          nullable: true
          type: number
        faceMatchDistanceThreshold:
          description: Optional face match distance threshold used to compare face event images. Defaults to 0.7.Valid range [0,1].
          format: float
          maximum: 1
          minimum: 0
          nullable: true
          type: number
        faceNameContains:
          description: "Optional filter by name. Matching is case-insensitive: the value is resolved against the org's registered people by substring and the face events of the matching people are returned; if no registered person matches, the face event is a match if its face name contains the value ignoring case. Set fuzzyNameMatch to also tolerate small spelling differences. The search will only be performed if the provided value is at least 3 characters long after trimming leading and trailing spaces. If both faceNameContains and faceNames are specified, faceNameContains takes a precedence."
          nullable: true
          type: string
        faceNames:
          description: Optional filter by people names.
          items:
            description: Optional filter by people names.
            nullable: true
            type: string
          nullable: true
          type: array
        fuzzyNameMatch:
          description: When true, faceNameContains also tolerates small spelling differences against the org's registered people; default false. Matching is case-insensitive either way.
          nullable: true
          type: boolean
        hasName:
          description: Optional filter by the presence or absence of a person name.
          nullable: true
          type: boolean
        labels:
          description: Optional filter by labels.
          items:
            description: Optional filter by labels.
            nullable: true
            type: string
          nullable: true
          type: array
        locationUuids:
          description: Optional filter by a set of locations.
          items:
            description: base 64 (url-safe) uuid string
            example: AAAAAAAAAAAAAAAAAAAAAA
            format: RUUID
            nullable: true
            type: string
          nullable: true
          type: array
        personUuids:
          description: Optional filter by a set of people.
          items:
            description: base 64 (url-safe) uuid string
            example: AAAAAAAAAAAAAAAAAAAAAA
            format: RUUID
            nullable: true
            type: string
          nullable: true
          type: array
        timestampFilter:
          $ref: "#/components/schemas/TimestampFilter"
      type: object
    TimestampFilter:
      description: Optional filter by an event timestamp. If not specified, the filter defaults to the last 7 days.
      properties:
        rangeEnd:
          description: End of the date range (inclusive).
          format: date-time
          nullable: true
          type: string
        rangeStart:
          description: Start of the date range (inclusive).
          format: date-time
          nullable: true
          type: string
      type: object
    Facerecognition_faceevent_FindSimilarFaceEventsByEmbeddingWSResponse:
      description: Response object containing face events similar to a face embedding with pagination information.
      properties:
        faceEvents:
          description: List of face events similar to the specified face embedding
          items:
            $ref: "#/components/schemas/Facerecognition_faceevent_ExternalFaceEvent"
          nullable: true
          type: array
        lastEvaluatedKey:
          description: Pagination key for retrieving the next page of similar face events
          example: next_page_key_123
          nullable: true
          type: string
      type: object
    Facerecognition_faceevent_ExternalFaceEvent:
      description: External face event object containing face recognition data with person matches, embeddings, and metadata.
      properties:
        detectionConfidence:
          description: Confidence value indicating the likelihood that the detected image is a face
          example: 0.98
          format: float
          nullable: true
          type: number
        deviceUuid:
          description: RUUID with optional appended facet information
          example: AAAAAAAAAAAAAAAAAAAAAA.v0
          format: DeviceFacetUuid
          nullable: true
          type: string
        embeddingConfidence:
          description: Confidence value associated with the embedding generated for the face image
          example: 0.95
          format: float
          nullable: true
          type: number
        eventTimestamp:
          description: Timestamp when the face event occurred
          example: 1640995200000
          format: int64
          nullable: true
          type: integer
        faceName:
          description: Name of the person that matched the face image. If selectedPersonMatch is not null, faceName will be equal to the name field of selectedPersonMatch.
          nullable: true
          type: string
        hasEmbedding:
          description: Whether the face event has an embedding
          example: true
          nullable: true
          type: boolean
        imageS3Key:
          description: S3 key for the face event image
          example: face-events/images/event_123.jpg
          nullable: true
          type: string
        locationUuid:
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          format: RUUID
          nullable: true
          type: string
        orgUuid:
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          format: RUUID
          nullable: true
          type: string
        personUuid:
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          format: RUUID
          nullable: true
          type: string
        selectedPersonMatch:
          $ref: "#/components/schemas/Facerecognition_faceevent_ExternalPersonMatch"
        subLocationsHierarchyKey:
          description: |
            A sequence of one or more base 64 (url-safe) uuid substrings.
            These substrings are separated by dots (.).
          example: AAAAAAAAAAAAAAAAAAAAAA.AAAAAAAAAAAAAAAAAAAAAA.AAAAAAAAAAAAAAAAAAAAAA
          format: SubLocationsHierarchyKey
          nullable: true
          pattern: ^([A-Za-z0-9\-_]{22})([.][A-Za-z0-9\-_]{22})*$
          type: string
        thumbnailS3Key:
          description: S3 key for the face event thumbnail
          example: face-events/thumbnails/event_123.jpg
          nullable: true
          type: string
        topPersonMatches:
          description: Top person matches found for the face image.
          items:
            $ref: "#/components/schemas/Facerecognition_faceevent_ExternalPersonMatch"
          nullable: true
          type: array
        uuid:
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          format: RUUID
          nullable: true
          type: string
      type: object
    Facerecognition_faceevent_ExternalPersonMatch:
      description: Person match information for face recognition events with confidence scoring.
      properties:
        confidence:
          description: Match confidence level expressed as a value in range[0,1]
          example: 0.95
          format: float
          nullable: true
          type: number
        faceId:
          description: Face ID associated with the person match
          example: face_12345
          nullable: true
          type: string
        name:
          description: Name of the person matched
          example: John Doe
          nullable: true
          type: string
        uuid:
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          format: RUUID
          nullable: true
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints).
      in: header
      name: x-auth-apikey
      type: apiKey
    oauth2:
      description: 'OAuth 2.0 authorization code flow with PKCE (`S256`). Send the access token as `Authorization: Bearer <token>`. Each operation lists the scopes it requires; a token without them is refused 403 with `WWW-Authenticate: Bearer error="insufficient_scope"`.'
      flows:
        authorizationCode:
          authorizationUrl: https://console.rhombus.com/oauth/authorize
          refreshUrl: https://auth-web.rhombussystems.com/oauth/token
          scopes:
            physical: Unlock doors and elevators, lockdown, alarms, speakers and robots
            read: View cameras, footage and settings
            write: Change settings and data
          tokenUrl: https://auth-web.rhombussystems.com/oauth/token
      type: oauth2
````
