> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.resemble.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.resemble.ai/_mcp/server.

# Search Identities

`POST https://app.resemble.ai/api/v2/identity/search`

Search your identities (plus any `global` identities) for matches against a media sample. Search is **multimodal**:

* **Audio** — voice matching against enrolled voice samples.
* **Image** — face/visual matching against enrolled reference photos, scored by embedding similarity (`score_type: "cosine"`). For the highest-fidelity person face confirmation, use the asynchronous [Detect pipeline](/detect/create).
* **Video** — not yet supported for synchronous search (returns `422`). Use the [Detect pipeline](/detect/create) for video identity matching.

## Request Body

| Field       | Type    | Required                          | Description                                                                                    |
| ----------- | ------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| `url`       | string  | One of `url`, `file`, `signed_id` | URL to the media sample to search for.                                                         |
| `file`      | file    | One of `url`, `file`, `signed_id` | Media file (multipart upload).                                                                 |
| `signed_id` | string  | One of `url`, `file`, `signed_id` | Signed ID from a [Secure Upload](/detect/secure-uploads).                                      |
| `modality`  | string  | ❌                                 | `audio` or `image`. Inferred from the media's content type when omitted (defaults to `audio`). |
| `top_k`     | integer | ❌                                 | Number of top matches to return (1–20). Defaults to 1.                                         |

## Example Request (audio)

```bash
curl --request POST 'https://app.resemble.ai/api/v2/identity/search' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/audio/sample_to_search.wav",
    "top_k": 5
  }'
```

## Example Request (image)

```bash
curl --request POST 'https://app.resemble.ai/api/v2/identity/search' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'file=@suspect_frame.jpg' \
  -F 'modality=image' \
  -F 'top_k=5'
```

## Response

`item` is an object keyed by the matched identity's UUID.

```json
{
  "success": true,
  "modality": "audio",
  "item": {
    "IDENTITY_UUID": {
      "name": "John Doe",
      "distance": 92.41
    },
    "IDENTITY_UUID_2": {
      "name": "Jane Smith",
      "distance": 61.73
    }
  }
}
```

`distance` is a 0–100 match score — **higher** means a closer match (an identical sample scores 100). Image matches additionally include `score_type`:

```json
{
  "success": true,
  "modality": "image",
  "item": {
    "IDENTITY_UUID": {
      "name": "Acme Corp",
      "distance": 88.31,
      "score_type": "cosine"
    }
  }
}
```

### Errors

| Status                     | Cause                                                         |
| -------------------------- | ------------------------------------------------------------- |
| `422 Unprocessable Entity` | No media supplied, or an unsupported modality (e.g. `video`). |
| `400 Bad Request`          | The search could not be completed.                            |