Safety & DetectionIdentity API

Create Identity

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

Create a new identity profile. Two request forms are supported:

  • Simple (audio-only) — flat parameters with an audio sample; creates a person identity with team visibility and enrolls the voice immediately.
  • Multimodal — a nested identity object with full control over type, visibility, and metadata. Reference media (voice samples, face photos, reference videos) is then enrolled with Add Reference Media.

To create an identity from an image, use the multimodal form and attach the photo in a second call — see Add Reference Media.

Simple Create (audio-only)

Request Body

FieldTypeRequiredDescription
namestring✅Speaker name/identifier.
urlstringOne of url, audio, signed_idURL to an audio sample of the speaker.
audiofileOne of url, audio, signed_idAudio file (multipart upload).
signed_idstringOne of url, audio, signed_idSigned ID from a Secure Upload.

Example

$curl --request POST 'https://app.resemble.ai/api/v2/identity' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "name": "John Doe",
>    "url": "https://example.com/audio/john_doe_sample.wav"
>  }'

Or upload the audio file directly:

$curl --request POST 'https://app.resemble.ai/api/v2/identity' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -F 'name=John Doe' \
>  -F 'audio=@john_doe_sample.wav'

Response

1{
2  "success": true,
3  "item": {
4    "uuid": "IDENTITY_UUID",
5    "name": "John Doe",
6    "created_at": "2026-01-01T00:00:00.000Z",
7    "audio_url": "https://app.resemble.ai/rails/active_storage/blobs/...",
8    "visibility": "team",
9    "identity_type": "person",
10    "notes": null,
11    "voice_profile_id": null,
12    "updated_at": "2026-01-01T00:00:00.000Z",
13    "project_count": 0
14  }
15}

success reflects whether the voice was enrolled for matching immediately; if enrollment is delayed, the identity is still created and enrollment completes in the background. Requests with no audio source return 422 Unprocessable Entity.

Multimodal Create

Request Body

FieldTypeRequiredDescription
identity.namestring✅Identity name (max 120 characters).
identity.identity_typestring❌person (default) or brand. See Identity Types.
identity.visibilitystring❌team (default) or global. See Visibility.
identity.notesstring❌Free-form notes.
identity.voice_profile_idstring❌Associated voice profile ID, if any.

Example

$curl --request POST 'https://app.resemble.ai/api/v2/identity' \
>  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>  -H 'Content-Type: application/json' \
>  --data '{
>    "identity": {
>      "name": "Acme Corp",
>      "identity_type": "brand",
>      "visibility": "team",
>      "notes": "Brand impersonation monitoring"
>    }
>  }'

Response

Returns 201 Created with the full Identity object:

1{
2  "uuid": "IDENTITY_UUID",
3  "name": "Acme Corp",
4  "identity_type": "brand",
5  "visibility": "team",
6  "notes": "Brand impersonation monitoring",
7  "voice_profile_id": null,
8  "created_at": "2026-01-01T00:00:00.000Z",
9  "updated_at": "2026-01-01T00:00:00.000Z",
10  "project_count": 0,
11  "voice_samples": [],
12  "face_photos": [],
13  "reference_videos": [],
14  "embeddings": [],
15  "projects": []
16}

Invalid parameters return 422 Unprocessable Entity with an errors object.

The multimodal form creates the profile only — enroll voice samples, face photos, or reference videos with Add Reference Media.