---
title: "Accept a suggestion as a competitor"
method: POST
path: "/suggestions/{suggestionId}/accept"
tags: ["entities"]
---

# Accept a suggestion as a competitor

`POST /suggestions/{suggestionId}/accept`

## Request

- Base URL: `https://shruwd.io/api/v1`
- URL: `https://shruwd.io/api/v1/suggestions/{suggestionId}/accept`
- Auth: HTTP bearer

Creates the competitor entity exactly as `POST /brands/{brandId}/entities`
would — the same exact-alias rule, the same `context_terms_required`
refusal for short or common-word names — and marks the suggestion
accepted. The name defaults to the suggested name; the domain defaults to
the one the answers linked, when they did.

## Request body

- AcceptSuggestionRequest
  - `name` string: Defaults to the suggested name.
  - `aliases` AliasInput[]: Defaults to the entity's name.
    - `alias` string, required: An exact string, matched on token boundaries. Not a pattern.
    - `kind` 'name' | 'product' | 'abbreviation' | 'misspelling'
    - `caseSensitive` boolean
  - `domains` string[]: Hosts or URLs; reduced to registrable domains. A citation of one of them counts for this entity.
  - `exclusions` string[]: Literal phrases that contain an alias but are not the entity ("arc welding" for "Arc").
  - `contextTerms` string[]: When non-empty, a mention counts only if one of these appears nearby. Required for short or common-word names. The entity's domains are added to them.

## Response `201`

Accepted; the competitor exists.

- object
  - `suggestion` Suggestion, required: A name the answers use that the brand does not track, with the evidence for suggesting it.
    - `suggestionId` string, required
    - `brandId` string, required
    - `name` string, required: The most frequent surface form in the answers.
    - `domainHint` string, nullable, required: The registrable domain of the name's own site, when the answers linked the name to it. A link to someone else's page is a citation, not the name's site, and gives no hint. Used as the entity's domain on acceptance unless overridden.
    - `state` 'open' | 'accepted' | 'dismissed', required
    - `share` number, required: Distinct responses in the cluster that named it, divided by the cluster's responses. In [0, 1].
    - `responses` integer, required
    - `clusterResponses` integer, required
    - `cluster` string, required: `*` for the whole prompt set, otherwise a prompt tag.
    - `samplePromptGroupId` string, nullable, required: One prompt whose answers named it.
    - `firstSeenAt` string, date-time, required
    - `lastSeenAt` string, date-time, required
    - `decidedAt` string, date-time, nullable, required
    - `entityId` string, nullable, required: The competitor it became, once accepted.
  - `entity` Entity, required
    - `entityId` string, required
    - `name` string, required
    - `isSelf` boolean, required: True for the brand itself.
    - `requiresContext` boolean, required: Mentions count only near one of `contextTerms`.
    - `needsContextTerms` boolean, required: The name or an alias is six characters or fewer or an ordinary English word, so the entity needs context terms to count only real mentions. True with `requiresContext` false means the entity is matching without them; set some with PUT /entities/{entityId}, or remove the alias.
    - `genericSpelling` string, nullable, required: The spelling, name or alias, that makes `needsContextTerms` true; null when none does.
    - `contextTerms` string[], required
    - `aliases` Alias[], required
      - `aliasId` string, required
      - `alias` string, required
      - `kind` 'name' | 'product' | 'abbreviation' | 'misspelling', required
      - `caseSensitive` boolean, required: True for acronyms: `SAP`, not `sap`.
    - `domains` string[], required
    - `exclusions` string[], required
    - `createdAt` string, date-time, required

## Other responses

- `404`: `not_found`: no such resource in this workspace.
- `409`: `suggestion_decided` (already accepted or dismissed) or `domain_taken`.
- `422`: `context_terms_required`, `invalid_alias`, `invalid_domain`.
- `default`: Every failure has this body.

---

[API](https://skmtc.dev/shruwd/apis/shruwd-api.md) · [All operations](https://skmtc.dev/shruwd/apis/shruwd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shruwd/apis/shruwd-api/revisions/64a5da079928?raw)