---
title: "Search identities"
method: POST
path: "/identity/search"
tags: ["identity"]
---

# Search identities

`POST /identity/search`

Search the team's identities (plus global identities) for matches against a media sample. Supports audio (voice matching) and image (face/visual matching); video is not yet supported for synchronous search.

## Headers

- `Authorization` string, required

## Request body

- object
  - `url` string, uri — URL to the media sample (one of url, file, signed_id is required)
  - `signed_id` string — Signed ID from a secure upload
  - `modality` 'audio' | 'image' — Inferred from the media's content type when omitted (defaults to audio)
  - `top_k` integer

## Response `200`

Search results

- IdentitySearchIdentitiesResponse200
  - `success` boolean
  - `modality` 'audio' | 'image'
  - `item` object — Matches keyed by identity UUID. distance is a 0-100 match score (higher is closer; an identical sample scores 100). Image matches include score_type "cosine".

## Other responses

- `400` — Search failed
- `422` — Missing media or unsupported modality

## Changes

> 6 revisions in range; 3 could not be searched.

- **2026-07-26** `5e92bebbaf1f` — 2 warning, 8 info
  - removed the request property `audio_url`
  - removed the optional property `matches` from the response with the `200` status
  - added the new optional request property `modality`
  - added the new optional request property `signed_id`
  - …6 more

[Change history](https://skmtc.dev/resemble/apis/api-reference/changes/identity/search/post.md)

---

[API](https://skmtc.dev/resemble/apis/api-reference.md) · [All operations](https://skmtc.dev/resemble/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/resemble/api-reference/revisions/e93597a6b425/schema)