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

# 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](/detect/identity/attachments).

To create an identity from an **image**, use the multimodal form and attach the photo in a second call — see [Add Reference Media](/detect/identity/attachments).

## Simple Create (audio-only)

### Request Body

| Field       | Type   | Required                           | Description                                               |
| ----------- | ------ | ---------------------------------- | --------------------------------------------------------- |
| `name`      | string | ✅                                  | Speaker name/identifier.                                  |
| `url`       | string | One of `url`, `audio`, `signed_id` | URL to an audio sample of the speaker.                    |
| `audio`     | file   | One of `url`, `audio`, `signed_id` | Audio file (multipart upload).                            |
| `signed_id` | string | One of `url`, `audio`, `signed_id` | Signed ID from a [Secure Upload](/detect/secure-uploads). |

### Example

```bash
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:

```bash
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

```json
{
  "success": true,
  "item": {
    "uuid": "IDENTITY_UUID",
    "name": "John Doe",
    "created_at": "2026-01-01T00:00:00.000Z",
    "audio_url": "https://app.resemble.ai/rails/active_storage/blobs/...",
    "visibility": "team",
    "identity_type": "person",
    "notes": null,
    "voice_profile_id": null,
    "updated_at": "2026-01-01T00:00:00.000Z",
    "project_count": 0
  }
}
```

`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

| Field                       | Type   | Required | Description                                                                           |
| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `identity.name`             | string | ✅        | Identity name (max 120 characters).                                                   |
| `identity.identity_type`    | string | ❌        | `person` (default) or `brand`. See [Identity Types](/detect/identity#identity-types). |
| `identity.visibility`       | string | ❌        | `team` (default) or `global`. See [Visibility](/detect/identity#visibility).          |
| `identity.notes`            | string | ❌        | Free-form notes.                                                                      |
| `identity.voice_profile_id` | string | ❌        | Associated voice profile ID, if any.                                                  |

### Example

```bash
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](/detect/identity#the-identity-object):

```json
{
  "uuid": "IDENTITY_UUID",
  "name": "Acme Corp",
  "identity_type": "brand",
  "visibility": "team",
  "notes": "Brand impersonation monitoring",
  "voice_profile_id": null,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "project_count": 0,
  "voice_samples": [],
  "face_photos": [],
  "reference_videos": [],
  "embeddings": [],
  "projects": []
}
```

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](/detect/identity/attachments).