> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search face

> Search for matching faces within a collection using a submitted image

This API endpoint allows you to search for matching faces within a collection using a submitted facial image. The system will compare the submitted image against all faces in the specified collection and return matching results.

## Request

### Headers

<ParamField header="x-api-key" type="string">
  The API key used for authentication and access control. This header parameter is required for authorization.
</ParamField>

### Body Parameters

<ParamField header="collectionId" type="string" required>
  Unique identifier of the collection where the face will be added.
</ParamField>

<ParamField header="requestName" type="string" required>
  Name that matches the face image
</ParamField>

<ParamField header="faceImage" type="string" required>
  Base64-encoded string representation of the face image.
</ParamField>

## Response

### Success Response (200)

<ResponseField name="message" type="string">
  A message indicating the success or error result
</ResponseField>

<ResponseField name="searchId" type="string">
  Identifier for the search request.
</ResponseField>

<ResponseField name="requestName" type="string">
  Name corresponding to the face image for the search operation.
</ResponseField>

<ResponseField name="option" type="object">
  Additional options and settings:

  **option\_liveness**: Indicates whether the liveness option is enabled or disabled in the settings.

  **liveNess\_threshold**: Threshold value for the liveness option, as configured in the Search Face threshold settings.

  **liveNessScore**: Score representing the result of the liveness check.

  **policy\_similarity**: Threshold value for similarity option.
</ResponseField>

<ResponseField name="faceIdList" type="array">
  List of face IDs that match the search criteria. Each item in the array is a unique identifier for a face submission.
</ResponseField>

### Error Responses

#### Bad Request (400)

<ResponseField name="errorCode" type="number">
  Identifies the specific error for troubleshooting:

  * 6030: CollectionId is required
  * 6031: RequestName is required
  * 6032: faceImage is missing
  * 6033: If the collection information doesn't exist
  * 6034: The collection has already been deleted
  * 6035: When a liveness error occurs
  * 6036: Image is too large
  * 6037: Image is not formatted correctly
  * 6038: Unspecified errors
</ResponseField>

<ResponseField name="message" type="string">
  Briefly describes the error. Please refer to the error code for details.
</ResponseField>

#### Forbidden (403)

<ResponseField name="errorCode" type="number">
  Identifies the specific error for troubleshooting:

  * 6039: API Key is required
  * 6040: Access Denied: API Key is unavailable
</ResponseField>

<ResponseField name="message" type="string">
  Briefly describes the error. Please refer to the error code for details.
</ResponseField>


## OpenAPI

````yaml POST /search
openapi: 3.1.0
info:
  title: Face ID API
  description: >-
    API for facial recognition and identity verification using Face ID
    technology
  version: 1.0.0
servers:
  - url: https://face.argosidentity.com
    description: Production server
security: []
paths:
  /search:
    post:
      tags:
        - Face ID
      summary: Search face in collection
      description: Search for matching faces within a collection using a submitted image
      operationId: searchFace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - collectionId
                - requestName
                - faceImage
              properties:
                collectionId:
                  type: string
                  description: Unique identifier of the collection to search in
                  example: col_123456789
                requestName:
                  type: string
                  description: Name that matches the face image
                  example: John Doe
                faceImage:
                  type: string
                  description: >-
                    Base64-encoded string representation of the face image to
                    search for
                  example: 9j/4AAQSkZJRgABAQAAAQ...
      responses:
        '200':
          description: Face search completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                    example: Search completed successfully
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        face_id:
                          type: string
                          description: Unique identifier for the matching face
                        user_name:
                          type: string
                          description: Name of the user associated with the matching face
                        similarity_score:
                          type: number
                          description: >-
                            Similarity score between the searched face and the
                            matching face
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: number
                    description: Error code
                    enum:
                      - 6035
                      - 6036
                      - 6037
                      - 6038
                  message:
                    type: string
                    description: Error message
        '403':
          description: Forbidden - Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: number
                    description: Error code
                    enum:
                      - 6039
                      - 6040
                  message:
                    type: string
                    description: Error message
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````