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

# Search the Face Index

> Find the Orbit profiles whose photos show a picked face.

Search the face index compares a picked face with the faces on Orbit profiles. It is the free first step of [face search](/concepts/search#face-search): a match shows a known profile at once.

```bash theme={"dark"}
curl -X POST "https://api.orbitsearch.com/v3/faces/index-search" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "face-source:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.jpg",
    "bbox": [212, 140, 388, 356]
  }'
```

## Request Body

| Field | Type | Description |
| - | - | - |
| `image_url` | string | The photo reference from [Detect faces](/api/search/faces-detect). |
| `bbox` | array of 4 numbers | The picked face's box from Detect faces. Required when the photo has more than one face. |

## Response

```json theme={"dark"}
{
  "status": "success",
  "payload": {
    "min_similarity": 0.52,
    "face": { "bbox": [212, 140, 388, 356] },
    "matches": [
      {
        "profile_id": "profile_123",
        "similarity": 0.81,
        "image_url": "https://example.com/example-person.jpg"
      }
    ]
  }
}
```

| Field | Type | Description |
| - | - | - |
| `min_similarity` | number | The lowest similarity a match can have. |
| `face.bbox` | array of 4 integers | The face Orbit compared, as it found it in the photo. |
| `matches` | array | Profiles whose photos show the same face, highest similarity first. The array is empty when the index has no match. |
| `matches[].profile_id` | string | The Orbit profile ID. Pass it to [Read a profile](/api/enrich/read-profile). |
| `matches[].similarity` | number | How alike the two faces are, from 0 to 1. |
| `matches[].image_url` | string | The profile photo that matched. |

Several matches can be the same person on different profiles, or look-alikes. Show them to your user to choose. To search the web for the face, [start a search](/api/search/search) with `signals.face_source`.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `developer_face_source_invalid` | `image_url` is a reference other than one from Detect faces, or `bbox` has the wrong shape. |
| 422 | `developer_v3_faces_source_face_not_found` | The box matches none of the faces in the photo, or the photo has several faces and the request has no `bbox`. |
| 502 | `developer_v3_faces_upstream_failed` | Face matching is temporarily unavailable. Retry later. |

## Authentication and Cost

This endpoint requires `search:read`. Searching the face index is free.


## OpenAPI

````yaml openapi.json POST /v3/faces/index-search
openapi: 3.1.0
info:
  title: Orbit API
  version: 3.0.0
  description: Search for people and enrich known Orbit profiles.
servers:
  - url: https://api.orbitsearch.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search
    description: Find people and poll search results.
  - name: Enrich
    description: Read or enrich known Orbit profiles.
  - name: Watchers
    description: Watch a profile on a schedule and read what each run found.
  - name: Webhooks
    description: Register endpoints that receive signed event deliveries.
paths:
  /v3/faces/index-search:
    post:
      tags:
        - Search
      summary: Search the Face Index
      description: >-
        Return the Orbit profiles whose photos show the picked face. Requires
        the `search:read` scope.
      operationId: searchFaceIndex
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaceSource'
      responses:
        '200':
          description: Profiles that show the picked face.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceIndexSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: The box matches none of the faces in the photo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: Face matching is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    FaceSource:
      type: object
      required:
        - image_url
      additionalProperties: false
      description: >-
        A face from a photo stored by `POST /v3/faces/detect`. On `POST
        /v3/search` it searches for the people the face could be.
      properties:
        image_url:
          type: string
          minLength: 1
          description: The photo reference returned by `POST /v3/faces/detect`.
        bbox:
          allOf:
            - $ref: '#/components/schemas/FaceBox'
          description: >-
            The picked face's box from `POST /v3/faces/detect`. Required when
            the photo has more than one face.
    FaceIndexSearchResponse:
      type: object
      required:
        - status
        - payload
      description: Orbit profiles that show the picked face.
      properties:
        status:
          type: string
          enum:
            - success
        payload:
          $ref: '#/components/schemas/FaceIndexSearch'
    ErrorResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - failed
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            requiredCredits:
              type: integer
              minimum: 0
              description: >-
                Credits required when the error is
                developer_api_credits_insufficient.
            remainingCredits:
              type: integer
              minimum: 0
              description: >-
                Available credits when the error is
                developer_api_credits_insufficient.
    FaceBox:
      type: array
      minItems: 4
      maxItems: 4
      items:
        type: number
        minimum: 0
      description: A face box `[x0, y0, x1, y1]` in the pixels of the upright photo.
      example:
        - 212
        - 140
        - 388
        - 356
    FaceIndexSearch:
      type: object
      required:
        - min_similarity
        - face
        - matches
      properties:
        min_similarity:
          type: number
        face:
          type: object
          required:
            - bbox
          properties:
            bbox:
              $ref: '#/components/schemas/FaceBox'
        matches:
          type: array
          items:
            $ref: '#/components/schemas/FaceIndexMatch'
    FaceIndexMatch:
      type: object
      required:
        - profile_id
        - similarity
        - image_url
      properties:
        profile_id:
          type: string
        similarity:
          type: number
          minimum: 0
          maximum: 1
        image_url:
          type: string
          description: The profile photo that matched.
  responses:
    BadRequest:
      description: The request is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The API key is missing or not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The API key does not have the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: The API key exceeded a rate limit.
      headers:
        Retry-After:
          description: Seconds to wait before another request.
          schema:
            type: integer
            minimum: 0
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Orbit API key
      description: Use an Orbit API key from the Developer Dashboard.

````

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