> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Identities Guide

> How to list identities and update identity profile fields and email signatures

## Overview

Use identities to decide who sends outbound messages from Enginy. The public API lets you list identities, inspect the mailboxes attached to each identity, update public profile fields, and automate the email signature.

## Find an Identity

Call `GET /v1/identities` to list identities available to your API key workspace.

```bash theme={null}
curl "https://openapi.enginy.ai/v1/identities?page=1&pageSize=25" \
  -H "x-api-key: $ENGINY_API_KEY"
```

Each identity includes:

| Field       | Notes                                                            |
| ----------- | ---------------------------------------------------------------- |
| `id`        | Use this as `identityId` in update and mailbox endpoints.        |
| `appUrl`    | Direct Enginy app URL for opening the identity.                  |
| `email`     | Primary email address stored on the identity.                    |
| `emails`    | All active mailbox email addresses associated with the identity. |
| `signature` | HTML appended to outbound emails sent from this identity.        |

## Update Profile Fields

Call `PATCH /v1/identities/{identityId}` to update public profile fields for one identity.

This endpoint currently requires an API key with the `ALL` scope. Enginy has an `IDENTITIES_READ` scope for reads, but there is not yet an identity-specific write scope in the public API key model.

```bash theme={null}
curl -X PATCH "https://openapi.enginy.ai/v1/identities/123" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Jane Doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "jobTitle": "VP Sales",
    "phoneNumber": "+34600000000",
    "linkedInUrl": "https://www.linkedin.com/in/jane-doe",
    "scheduleMeetingUrl": "https://cal.example.com/jane",
    "timezone": "Europe/Madrid"
  }'
```

Writable fields:

| Field                 | Type              |
| --------------------- | ----------------- |
| `name`                | string or null    |
| `firstName`           | string or null    |
| `lastName`            | string or null    |
| `jobTitle`            | string or null    |
| `email`               | string or null    |
| `phoneNumber`         | string or null    |
| `linkedInUrl`         | string or null    |
| `scheduleMeetingUrl`  | string or null    |
| `timezone`            | string or null    |
| `profileOverview`     | string or null    |
| `keyResponsibilities` | string or null    |
| `interests`           | string\[] or null |
| `languages`           | string\[] or null |
| `gender`              | string or null    |
| `seniorityLevel`      | string or null    |
| `educations`          | string or null    |
| `previousPositions`   | string or null    |
| `countryCode`         | string or null    |
| `signature`           | string or null    |

You only need to send the fields you want to change. At least one field is required.

## Update Email Signature

Send `signature` as HTML. Enginy stores the exact HTML in `signature` and appends it to outbound emails sent from the identity.

```bash theme={null}
curl -X PATCH "https://openapi.enginy.ai/v1/identities/123" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "signature": "<p>Jane Doe<br>VP Sales at Enginy</p><p><a href=\"https://enginy.ai\">enginy.ai</a></p>"
  }'
```

Example response fields:

```json theme={null}
{
  "signature": "<p>Jane Doe<br>VP Sales at Enginy</p><p><a href=\"https://enginy.ai\">enginy.ai</a></p>"
}
```

## Clear Email Signature

Send `signature: null` to remove the signature.

```bash theme={null}
curl -X PATCH "https://openapi.enginy.ai/v1/identities/123" \
  -H "x-api-key: $ENGINY_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "signature": null }'
```

## Mailboxes

The `email` field on the identity is the primary identity email address, but it does not configure mailbox credentials by itself. Use the mailbox endpoints when you need to inspect or configure sending mailboxes:

* `GET /v1/identities/{identityId}/mailboxes`
* `POST /v1/identities/{identityId}/mailboxes`

## Validation and Errors

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| `400`  | The identity ID or request body is invalid.                          |
| `404`  | The identity does not exist in the API key workspace or was deleted. |