Entity Management

Creating Entities

Changed on

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

post/v1/projects/{projectId}/datasets/{name}/entities

Request

  • Base URL
    / (relative, and the document was published on a file host, not at the API’s origin)
  • URL
    /v1/projects/{projectId}/datasets/{name}/entities
  • Auth
    none declared

Path parameters

projectIdnumber required

The numeric ID of the Project

namestring required

Name of the Dataset

Request body */*

OR

Example request

{
  "data": {
    "firstName": "John",
    "age": "88"
  }
}

Response

OK

uuidstring

The uuid of the Entity that uniquely identifies the Entity.

createdAtstring

ISO date format. The time that the server received the Entity.

updatedAtstring

Timestamp of the last update in ISO date format. null when there is only one version of the Entity.

deletedAtstring

Timestamp of the deletion in ISO date format. null if the Entity is not deleted.

creatorIdnumber

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

Example response

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-04-18T23:42:11.406Z",
  "updatedAt": "2018-04-18T23:42:11.406Z",
  "deletedAt": "2018-04-18T23:42:11.406Z",
  "creatorId": 1,
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "version": 2,
    "baseVersion": 1,
    "branchId": "b0e927b6-958a-42f6-8344-1deb37ee9672",
    "trunkVersion": 1,
    "branchBaseVersion": 1,
    "data": {
      "firstName": "John",
      "age": "88"
    },
    "dataReceived": {
      "firstName": "John",
      "age": "88",
      "label": "John (88)"
    }
  }
}

Changes