> 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.

# Identity API

> **Beta:** Reach out to the Resemble team to join the preview program.

Create and manage **multimodal identity profiles** — enrolled from voice samples, face photos, and reference videos — then search incoming media against your known identities.

## Identity Types

| Type     | Description                                                                                                  |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| `person` | A real person. Face matching uses face recognition against up to 5 reference photos (3 recommended).         |
| `brand`  | A brand, logo, or visual mark. Visual matching uses embedding similarity over all uploaded reference images. |

Voice matching works identically for both types.

## Visibility

| Visibility       | Description                                                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `team` (default) | The identity is only matchable by your own team's searches and detections.                                                                         |
| `global`         | The identity is enrolled into the shared monitoring pool, so detections from any team can be matched against it (used for large-scale monitoring). |

## The Identity Object

```json
{
  "uuid": "IDENTITY_UUID",
  "name": "John Doe",
  "identity_type": "person",
  "visibility": "team",
  "notes": "Executive voice profile",
  "voice_profile_id": null,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "project_count": 1,
  "voice_samples": [
    { "id": 101, "filename": "sample.wav", "byte_size": 1048576, "content_type": "audio/wav" }
  ],
  "face_photos": [
    { "id": 102, "filename": "headshot.jpg", "byte_size": 204800, "content_type": "image/jpeg" }
  ],
  "reference_videos": [],
  "embeddings": [
    { "modality": "voice", "status": "ready", "attachment_count": 1, "computed_at": "2026-01-01T00:00:05.000Z" }
  ],
  "projects": [
    { "uuid": "PROJECT_UUID", "name": "Brand Monitoring" }
  ]
}
```

Reference media is held per modality (`voice_samples`, `face_photos`, `reference_videos`) and processed asynchronously — the `embeddings` array reports each modality's processing status, and a modality becomes searchable once its embedding status is `ready`.

## Typical Workflow

1. **Create** an identity — in one call with an audio sample, or as a profile with a chosen type and visibility ([Create Identity](/detect/identity/create)).
2. **Enroll** reference media — voice samples, face photos, reference videos ([Add Reference Media](/detect/identity/attachments)).
3. **Search** incoming audio or images against your identities ([Search Identities](/detect/identity/search)).
4. **Delete** identities you no longer need ([Delete Identity](/detect/identity/delete)).