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, 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)

Example — enroll a face photo

$
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

$
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:

1
{
2
  "uuid": "IDENTITY_UUID",
3
  "name": "John Doe",
4
  "identity_type": "person",
5
  "visibility": "team",
6
  "notes": null,
7
  "voice_profile_id": null,
8
  "created_at": "2026-01-01T00:00:00.000Z",
9
  "updated_at": "2026-01-01T00:00:10.000Z",
10
  "project_count": 0,
11
  "voice_samples": [],
12
  "face_photos": [
13
    { "id": 102, "filename": "headshot.jpg", "byte_size": 204800, "content_type": "image/jpeg" }
14
  ],
15
  "reference_videos": [],
16
  "embeddings": [
17
    { "modality": "face", "status": "ready", "attachment_count": 1, "computed_at": "2026-01-01T00:00:12.000Z" }
18
  ],
19
  "projects": []
20
}

Errors

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.

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