---
title: "Upsert Identity"
method: PUT
path: "/v1/identities/"
tags: ["identities", "identities"]
---

# Upsert Identity

`PUT /v1/identities/`

## Headers

- `X-Project` string, nullable — The project slug to associate with the identity (cloud only).

## Request body

- IdentityUpsert
  - `identifier_key` string, required — External, user-generated identifier key of the identity.
  - `name` string, required — The name of the identity.
  - `identity_type` 'org' | 'user' | 'other', required — Enum to represent the type of the identity.
  - `project_id` string, nullable — The project id of the identity, if applicable.
  - `agent_ids` string[], nullable — The agent ids that are associated with the identity.
  - `block_ids` string[], nullable — The IDs of the blocks associated with the identity.
  - `properties` IdentityProperty[], nullable — List of properties associated with the identity.
    - `key` string, required — The key of the property
    - `value` union, required — The value of the property
      - string
      - integer
      - number
      - boolean
      - object
    - `type` 'string' | 'number' | 'boolean' | 'json', required — Enum to represent the type of the identity property.

## Response `200`

Successful Response

- Identity
  - `id` string — The human-friendly ID of the Identity
  - `identifier_key` string, required — External, user-generated identifier key of the identity.
  - `name` string, required — The name of the identity.
  - `identity_type` 'org' | 'user' | 'other', required — Enum to represent the type of the identity.
  - `project_id` string, nullable — The project id of the identity, if applicable.
  - `agent_ids` string[], required — The IDs of the agents associated with the identity.
  - `block_ids` string[], required — The IDs of the blocks associated with the identity.
  - `properties` IdentityProperty[] — List of properties associated with the identity
    - `key` string, required — The key of the property
    - `value` union, required — The value of the property
      - string
      - integer
      - number
      - boolean
      - object
    - `type` 'string' | 'number' | 'boolean' | 'json', required — Enum to represent the type of the identity property.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.dev/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yu-code666/letta-api/revisions/6cec99480c13/schema)