---
title: "Creating Entities"
method: POST
path: "/v1/projects/{projectId}/datasets/{name}/entities"
tags: ["Entity Management"]
---

# Creating Entities

`POST /v1/projects/{projectId}/datasets/{name}/entities`

Creates one or more Entities in the Dataset.

For creating **a single Entity**, the request body takes a JSON representation of the Entity, which has the following properties:

  1. A `data` object containing values for the user-defined Dataset properties. (Not all properties have to have values.)
  2. A `label` property, which cannot be blank or an empty string. (This is used as a human-readable label in Forms that consume Entities.)
  3. An optional `uuid` property. If the `uuid` is not specified, Central will generate a UUID for an Entity with the provided data and label.

`
  {
    "label": "John Doe",
    "data": {
      "firstName": "John",
      "age": "22"
    }
  }
`

The value type of all properties is `string`.

For creating **multiple Entities** in bulk, the request body takes an array `entities` containing a list of Entity objects as described above. The bulk entity version also takes a `source` property with a required `name` field and optional `size`, for example to capture the filename and size of a bulk upload source.

`
  {
    "entities": [...], "source": {"name": "file.csv", "size": 100}
  }
`

You can provide header `X-Action-Notes` to store the metadata about the request. The metadata can retrieved using [Entity Audit Log](/central-api-entity-management/#entity-audit-log)

## Path parameters

- `projectId` number, required
- `name` string, required

## Response `200`

OK

- Entity
  - `uuid` string — The `uuid` of the Entity that uniquely identifies the Entity.
  - `createdAt` string — ISO date format. The time that the server received the Entity.
  - `updatedAt` string — Timestamp of the last update in ISO date format. `null` when there is only one version of the Entity.
  - `deletedAt` string — Timestamp of the deletion in ISO date format. `null` if the Entity is not deleted.
  - `creatorId` number — The ID of the Actor (App User, User, or Public Link) that originally created the Entity.
  - `conflict` 'soft' | 'hard' — Type of the conflict. `hard`: baseVersion conflicts and multiple versions update the same property `soft`: baseVersion conflicts but data updates are independent
  - `currentVersion` EntityVersion
    - `label` string — Label of the Entity
    - `current` boolean — if the version is the latest one
    - `creatorId` number — The ID of the Actor (App User, User, or Public Link) that originally created the Entity.
    - `userAgent` string — The self-identified `userAgent` of the device that created the `Entity` version.
    - `conflictingProperties` string[] — list of properties updated offline simultaneously.
    - `version` number — The version number of the Entity. Each update increments this number.
    - `baseVersion` number — The version number of the version that was the "base version" of this version.
    - `branchId` string — The uuid of a branch linking multiple offline entity updates together.
    - `trunkVersion` number — The version number of the last known base server version of an entity, in the case of an offline branch of updates.
    - `branchBaseVersion` number — The base version of the entity according to the submission. In the case of an offline branch of updates, this may not match the version of the base submission on Central.
    - `data` DataExample
      - `firstName` string
      - `age` string
    - `dataReceived` DataReceivedExample
      - `firstName` string
      - `age` string
      - `label` string

## Changes

- **2026-02-24** `e92ddd4b9e5d` — 1 info
  - endpoint added
- **2025-03-13** `e8c2858fd4eb` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/getodk/apis/odk-central-api/changes/v1/projects/:projectId/datasets/:name/entities/post.md)

---

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