---
title: "Add a Synonym to an Entity"
method: POST
path: "/v3/entities/{id}/synonyms"
tags: ["Entity Synonyms"]
---

# Add a Synonym to an Entity

`POST /v3/entities/{id}/synonyms`

## Path parameters

- `id` string, required

## Query parameters

- `bucket` string

## Request body

- AddEntitySynonymRequestV3 — Request body for `POST /v3/entities/{id}/synonyms`.
  - `text` string, required — The human-readable synonym surface form to attach (e.g. `Acme Corp`, `ACME`). It is normalized (lowercased, whitespace-folded) for the uniqueness key and the matcher's exact-match path.
  - `locale` string — Optional BCP 47 locale tag (e.g. `en-US`) for language-specific synonyms.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- EntitySynonymV3 — One synonym attached to an entity.
  - `synonymID` string, required — Stable public identifier for the synonym (`esn_...`).
  - `text` string, required — The human-readable synonym as authored.
  - `normalizedText` string, required — Lowercased, whitespace-folded form of `text`.
  - `source` 'extracted' | 'customer_defined' | 'sme_approved', required — Provenance of the synonym. `customer_defined` and `sme_approved` synonyms are deletable; `extracted` synonyms are resolver-owned and cannot be deleted.
  - `locale` string — Optional BCP 47 locale tag, when one was supplied.
  - `createdAt` string, date-time, required — Creation timestamp of the synonym (RFC 3339).

## Changes

- **2026-06-17** `d7092283f192` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/bem-team/apis/bem-api/changes/v3/entities/:id/synonyms/post.md)

---

[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)