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

# Add Reference Media

`POST https://app.resemble.ai/api/v2/identity/{uuid}/attachments`

Attach a reference media file to an identity, one modality at a time. This is how face photos are enrolled for image matching — [create the identity](/detect/identity/create), then attach media to it. It also adds voice samples or reference videos to any existing identity.

The modality's embedding recomputes asynchronously after each change; the media becomes searchable once its status in the identity's `embeddings` array is `ready`.

## Request Body (multipart)

| Field      | Type   | Required | Description                  |
| ---------- | ------ | -------- | ---------------------------- |
| `modality` | string | ✅        | `voice`, `face`, or `video`. |
| `file`     | file   | ✅        | The media file to attach.    |

## Example — enroll a face photo

```bash
curl --request POST 'https://app.resemble.ai/api/v2/identity/IDENTITY_UUID/attachments' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'modality=face' \
  -F 'file=@headshot.jpg'
```

## Example — add a voice sample

```bash
curl --request POST 'https://app.resemble.ai/api/v2/identity/IDENTITY_UUID/attachments' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -F 'modality=voice' \
  -F 'file=@john_doe_sample.wav'
```

### Response

Returns `201 Created` with the updated [Identity object](/detect/identity#the-identity-object):

```json
{
  "uuid": "IDENTITY_UUID",
  "name": "John Doe",
  "identity_type": "person",
  "visibility": "team",
  "notes": null,
  "voice_profile_id": null,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:10.000Z",
  "project_count": 0,
  "voice_samples": [],
  "face_photos": [
    { "id": 102, "filename": "headshot.jpg", "byte_size": 204800, "content_type": "image/jpeg" }
  ],
  "reference_videos": [],
  "embeddings": [
    { "modality": "face", "status": "ready", "attachment_count": 1, "computed_at": "2026-01-01T00:00:12.000Z" }
  ],
  "projects": []
}
```

### Errors

| Status                     | Cause                                                                         |
| -------------------------- | ----------------------------------------------------------------------------- |
| `400 Bad Request`          | Missing or invalid `modality`, or missing `file`.                             |
| `404 Not Found`            | The identity does not exist or belongs to another team.                       |
| `422 Unprocessable Entity` | Face photo limit reached — a `person` identity accepts at most 5 face photos. |

## Remove Reference Media

`DELETE https://app.resemble.ai/api/v2/identity/{uuid}/attachments/{attachment_id}`

`attachment_id` is the `id` of an entry in the identity's `voice_samples`, `face_photos`, or `reference_videos` array. Returns `204 No Content`; the affected modality's embedding recomputes without the removed file. Returns `404 Not Found` if the attachment does not belong to the identity.

```bash
curl --request DELETE 'https://app.resemble.ai/api/v2/identity/IDENTITY_UUID/attachments/102' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```