Entity Management#

(introduced: version 2023.3)

⚠️ In this API and in the related ODK XForms specification, collections of Entities are referred to as Datasets. The term "Entity List" is used for this concept in the Central frontend UI, user facing documentation, and all other text intended for end users who are not developers.

Entities are data objects that can be shared between Forms to support workflows with multiple steps. They can be created either through form design or through this API. A collection of Entities is a Dataset.

Entities Metadata#

GET /projects/{projectId}/datasets/{name}/entities

This endpoint returns a list of the Entities of a Dataset. Please note that this endpoint only returns metadata of the entities not the data. If you want to get the data of all entities then please refer to OData Dataset ServiceYou can provide ?deleted=true to get only deleted entities.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

Response

HTTP Status: 200

Content Type: application/json

[
  {
    "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "updatedAt": "2018-03-21T12:45:02.312Z",
    "deletedAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "currentVersion": {
      "label": "John (88)",
      "current": true,
      "createdAt": "2018-03-21T12:45:02.312Z",
      "creatorId": 1,
      "userAgent": "Enketo/3.0.4"
    }
  }
]

array

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

HTTP Status: 200

Content Type: application/json; extended

[
  {
    "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "createdAt": "2018-01-19T23:58:03.395Z",
    "updatedAt": "2018-03-21T12:45:02.312Z",
    "deletedAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "creator": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    },
    "currentVersion": {
      "label": "John (88)",
      "current": true,
      "createdAt": "2018-03-21T12:45:02.312Z",
      "creatorId": 1,
      "userAgent": "Enketo/3.0.4",
      "creator": {
        "createdAt": "2018-04-18T23:19:14.802Z",
        "displayName": "My Display Name",
        "id": 115,
        "type": "user",
        "updatedAt": "2018-04-18T23:42:11.406Z",
        "deletedAt": "2018-04-18T23:42:11.406Z"
      }
    }
  }
]

array

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

creator

object

expand

createdAt

string

ISO date format

Example: 2018-04-18 23:19:14.802000+00:00

displayName

string

All Actors, regardless of type, have a display name

Example: My Display Name

id

number

Example: 115.0

type

enum

The type of actor

expand

user

string

field_key

string

public_link

string

singleUse

string

updatedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Creating an Entity#

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

Creates an Entity in the Dataset. Request body takes the JSON representation of the Entity. It should have uuid and label property in addition to the user-defined properties of the Dataset in data property.

Value type of all properties is string.

You can provide header X-Action-Notes to store the metadata about the request. The metadata can retrieved using Entity Audit Log

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

Request body

{
  "uuid": "54a405a0-53ce-4748-9788-d23a30cc3afa",
  "label": "John Doe (88)",
  "data": {
    "firstName": "John",
    "age": "88"
  }
}

object

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

label

string

Label of the Entity

data

object

expand

firstName

string

Example: John

age

string

Example: 88

Response

HTTP Status: 200

Content Type: application/json

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "deletedAt": "2018-03-21T12:45:02.312Z",
  "creatorId": 1,
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "data": {
      "firstName": "John",
      "age": "88"
    }
  }
}

object

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

data

object

expand

firstName

string

Example: John

age

string

Example: 88

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

Example: 403.1

message

string

Example: The authenticated actor does not have rights to perform that action.

Getting Entity Details#

GET /projects/{projectId}/datasets/{name}/entities/{uuid}

This returns the metadata and current data of an Entity

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

uuid

string

UUID of the Entity

Example: 54a405a0-53ce-4748-9788-d23a30cc3afa

Response

HTTP Status: 200

Content Type: application/json

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "deletedAt": "2018-03-21T12:45:02.312Z",
  "creatorId": 1,
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "data": {
      "firstName": "John",
      "age": "88"
    }
  }
}

array

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

data

object

expand

firstName

string

Example: John

age

string

Example: 88

HTTP Status: 200

Content Type: application/json; extended

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "deletedAt": "2018-03-21T12:45:02.312Z",
  "creatorId": 1,
  "creator": {
    "createdAt": "2018-04-18T23:19:14.802Z",
    "displayName": "My Display Name",
    "id": 115,
    "type": "user",
    "updatedAt": "2018-04-18T23:42:11.406Z",
    "deletedAt": "2018-04-18T23:42:11.406Z"
  },
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "data": {
      "firstName": "John",
      "age": "88"
    },
    "creator": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
}

array

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

creator

object

expand

createdAt

string

ISO date format

Example: 2018-04-18 23:19:14.802000+00:00

displayName

string

All Actors, regardless of type, have a display name

Example: My Display Name

id

number

Example: 115.0

type

enum

The type of actor

expand

user

string

field_key

string

public_link

string

singleUse

string

updatedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

data

object

expand

firstName

string

Example: John

age

string

Example: 88

HTTP Status: 403

Content Type: application/json; extended

{
  "code": "pencil",
  "message": "pencil"
}

object

code

string

message

string

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Deleting an Entity#

DELETE /projects/{projectId}/datasets/{name}/entities/{uuid}

Use this API to delete an Entity. With this API, Entity is soft-deleted, which means it is still in the database and you can retreive it by passing ?deleted=true to GET /projects/:id/datasets/:name/entities. In the future, we will provide a way to restore deleted entities and purge deleted entities.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

uuid

string

UUID of the Entity

Example: 54a405a0-53ce-4748-9788-d23a30cc3afa

Response

HTTP Status: 200

Content Type: application/json

{
  "message": "Success"
}

object

message

string

Example: Success

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Updating an Entity#

PATCH /projects/{projectId}/datasets/{name}/entities/{uuid}

Use this API to update one or all properties of an Entity. It will throw 400 - Bad Request if any of the updating properties doesn't exist in the dataset.

To unset value of any property, you can set it to empty string (""). Setting it to null will throw an error.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

uuid

string

UUID of the Entity

Example: 54a405a0-53ce-4748-9788-d23a30cc3afa

Request body

{
  "label": "John Doe (88)",
  "data": {
    "firstName": "John",
    "age": "88"
  }
}

object

label

string

Label of the Entity

data

object

expand

firstName

string

Example: John

age

string

Example: 88

Response

HTTP Status: 200

Content Type: application/json

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "updatedAt": "2018-03-21T12:45:02.312Z",
  "deletedAt": "2018-03-21T12:45:02.312Z",
  "creatorId": 1,
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "data": {
      "firstName": "John",
      "age": "88"
    }
  }
}

object

uuid

string

The uuid of the Entity that uniquely identifies the Entity.

Example: uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44

createdAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

updatedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

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

Example: 2018-04-18 23:42:11.406000+00:00

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

currentVersion

object

expand

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

data

object

expand

firstName

string

Example: John

age

string

Example: 88

HTTP Status: 403

Content Type: application/json; extended

{
  "code": "pencil",
  "message": "pencil"
}

object

code

string

message

string

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Listing Versions#

GET /projects/{projectId}/datasets/{name}/entities/{uuid}/versions

This returns the Entity metadata and data for every version of this Entity, in ascending creation order.

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to return a creator data object alongside the creatorId Actor ID reference.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

uuid

string

UUID of the Entity

Example: 54a405a0-53ce-4748-9788-d23a30cc3afa

Response

HTTP Status: 200

Content Type: application/json

[
  {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "data": {
      "firstName": "John",
      "age": "88"
    }
  }
]

array

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

data

object

expand

firstName

string

Example: John

age

string

Example: 88

HTTP Status: 200

Content Type: application/json; extended

[
  {
    "label": "John (88)",
    "current": true,
    "createdAt": "2018-03-21T12:45:02.312Z",
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "data": {
      "firstName": "John",
      "age": "88"
    },
    "creator": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
]

array

label

string

Label of the Entity

Example: John (88)

current

boolean

if the version is the latest one

Example: true

creatorId

number

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

Example: 1

userAgent

string

The self-identified userAgent of the device that created the Entity version.

Example: Enketo/3.0.4

data

object

expand

firstName

string

Example: John

age

string

Example: 88

reator

object

expand

createdAt

string

ISO date format

Example: 2018-04-18 23:19:14.802000+00:00

displayName

string

All Actors, regardless of type, have a display name

Example: My Display Name

id

number

Example: 115.0

type

enum

The type of actor

expand

user

string

field_key

string

public_link

string

singleUse

string

updatedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

deletedAt

string

ISO date format

Example: 2018-04-18 23:42:11.406000+00:00

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Getting changes between Versions#

GET /projects/{projectId}/datasets/{name}/entities/{uuid}/diffs

This returns the changes, or edits, between different versions of an Entity. These changes are returned as an array of arrays. Between two Entities, there is an array of objects representing how each property changed. This change object contains the old and new values, as well as the property name.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

uuid

string

UUID of the Entity

Example: 54a405a0-53ce-4748-9788-d23a30cc3afa

Response

HTTP Status: 200

Content Type: application/json

[
  [
    {
      "new": "John",
      "old": "Dana",
      "propertyName": "firstName"
    },
    {
      "new": "Doe",
      "old": "Roe",
      "propertyName": "lastName"
    },
    {
      "new": "John Doe",
      "old": "Jane Roe",
      "propertyName": "label"
    }
  ],
  [
    {
      "new": "Robert",
      "old": "Doe",
      "propertyName": "firstName"
    },
    {
      "new": "Robert Doe",
      "old": "Doe Doe",
      "propertyName": "label"
    }
  ]
]

array

None

object

expand

new

string

The new value of this property.

Example: John

old

string

The old value of this property.

Example: Jane

propertyName

string

The name of the property that is changed.

Example: name

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string

Entity Audit Log#

GET /projects/{projectId}/datasets/{name}/entities/{uuid}/audits

Returns Server Audit Logs relating to an Entity. They will be returned most recent first.

Request

Parameters

projectId

number

The numeric ID of the Project

Example: 16

name

string

Name of the Dataset

Example: people

uuid

string

UUID of the Entity

Example: 54a405a0-53ce-4748-9788-d23a30cc3afa

Response

HTTP Status: 200

Content Type: application/json

[
  {
    "actorId": 42,
    "action": "entity.create",
    "acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "loggedAt": "2018-04-18T23:19:14.802Z"
  }
]

array

actorId

number

The ID of the actor, if any, that initiated the action.

Example: 42

action

string

The action that was taken.

Example: form.create

acteeId

string

The ID of the permissioning object against which the action was taken.

Example: 85cb9aff-005e-4edd-9739-dc9c1a829c44

details

object

Additional details about the action that vary according to the type of action.

loggedAt

string

ISO date format

Example: 2018-04-18T23:19:14.802Z

HTTP Status: 403

Content Type: application/json

{
  "code": "403.1",
  "message": "The authenticated actor does not have rights to perform that action."
}

object

code

string

message

string