---
title: "Bulk Seed Entities"
method: POST
path: "/v3/entities/bulk"
tags: ["Entity Bulk Seed"]
---

# Bulk Seed Entities

`POST /v3/entities/bulk`

## Request body

- BulkSeedEntitiesRequestV3 — Request body for `POST /v3/entities/bulk`.
  - `bucket` string — Optional bucket public ID (`bkt_...`) to seed into. Omit to use the account+environment default bucket.
  - `entities` BulkSeedEntityInputV3[], required — The entities to seed. Must be non-empty.
    - `canonical` string, required — The canonical (longest / most descriptive) surface form for the entity, e.g. `Acme Corporation`. Required. Normalized (lowercased, whitespace-folded) for the uniqueness key.
    - `type` string, required — The entity type name, e.g. `instrument` or `organization`. Required. Resolved against your taxonomy and created if it does not yet exist.
    - `description` string — Optional free-form description of the entity.
    - `synonyms` string[] — Optional additional surface forms to attach as `customer_defined` synonyms.
    - `attributes` object — Optional per-entity structured attribute values, e.g. `{ "manufacturer": "Acme", "dosageMg": 50 }`. When the entity's type declares an attribute schema, keys not present in that schema cause the row to be rejected.
  - `onConflict` 'merge' — Conflict strategy for an entity that already exists. Only `merge` is supported and it is the default: synonyms are added additively, a longer description replaces the old one, and attributes are merged with new keys winning.

## Response `200`

The request has succeeded.

- BulkSeedSyncResponseV3 — `200` response for a synchronously processed (small) batch.
  - `results` SeedRowResultV3[], required — Per-row outcomes, in request order.
    - `canonical` string, required — The canonical name from the input row.
    - `outcome` 'created' | 'merged-with' | 'rejected', required — What happened to this row: `created` (new entity), `merged-with` (matched an existing entity), or `rejected` (see `reason`).
    - `entityID` string — Public ID (`ent_...`) of the created or merged entity. Absent when rejected.
    - `reason` string — Human-readable explanation when `outcome` is `rejected`.
  - `summary` SeedSummaryV3, required — Per-outcome tally across a batch.
    - `created` integer, required — Number of rows that created a new entity.
    - `merged` integer, required — Number of rows merged into an existing entity.
    - `rejected` integer, required — Number of rows rejected.

## Other responses

- `202` — The request has been accepted for processing, but processing has not yet completed.

## Changes

> 42 revisions in range; 1 could not be searched.

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

[Change history](https://skmtc.dev/bem-team/apis/bem-api/changes/v3/entities/bulk/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)