---
title: "Update Entity"
method: PATCH
path: "/v3/entities/{id}"
tags: ["Entity Curation"]
---

# Update Entity

`PATCH /v3/entities/{id}`

## Path parameters

- `id` string, required

## Query parameters

- `bucket` string

## Request body

- UpdateEntityRequestV3 — Request body for `PATCH /v3/entities/{id}`. Every field is optional, but at least one must be present.
  - `status` 'approved' | 'rejected' — Transition the entity's curation status. Only `approved` or `rejected` are accepted, and only from `extracted` or `proposed` (any other transition is rejected with `409`).
  - `assignedTypeID` string — The `ety_...` public ID of the type to assign (overriding the bem-inferred type). The empty string clears the assignment. Omit to leave unchanged.
  - `canonical` string — Replace the entity's canonical surface form (re-derives its normalized form).
  - `addSynonyms` string[] — Surface forms to attach as `customer_defined` synonyms.
  - `removeSynonymIDs` string[] — `esn_...` synonym IDs to soft-delete. Only `customer_defined` / `sme_approved` synonyms may be removed; an `extracted` synonym is rejected with `409`.
  - `locale` string — Optional BCP 47 locale tag stamped on any added synonyms.

## Response `200`

The request has succeeded.

- EntityResponseV3 — An entity record, including its curation status and assigned type.
  - `entityID` string, required — Public ID (`ent_...`).
  - `canonical` string, required — The canonical (longest / most descriptive) surface form.
  - `type` string, required — The entity's effective type name (assigned type if set, else inferred).
  - `description` string — Free-form description.
  - `mentionCount` integer, required — Total mentions across parsed documents.
  - `surfaceForms` string[], required — Distinct surface forms resolved to this entity.
  - `createdAt` string, date-time, required — Creation timestamp.
  - `updatedAt` string, date-time, required — Last-update timestamp.
  - `status` 'extracted' | 'proposed' | 'approved' | 'rejected', required — Curation lifecycle state.
  - `typeID` string — `ety_...` public ID of the assigned type, when one is set.
  - `validatedAt` string, date-time — When the entity was approved/rejected. Present only once validated.
  - `validatedByUserID` string — `usr_...` public ID of the validating user (dashboard transitions only).

---

[API](https://skmtc.dev/bem-team/apis/bem-api.md) · [All operations](https://skmtc.dev/bem-team/apis/bem-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bem-team/bem-api/revisions/a6e4624117c6/schema)