v4

latestOpenAPI 3.0.22026-07-3188146256.6 KB

Entities

updateEntity

Updates an Entity

Activity

If no activity_id query parameter is provided, implicitly creates Activity of type EntityUpdated

Relations

To create a relation, store a property that defines a $relation array.

Example:

{
  "contacts": {
    "$relation": [
      { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
    ]
  }
}

The items in $relation support two properties:

entity_id - The ID of the entity to link
_tags - Tags or labels for the relation (optional)

put/v1/entity/{slug}/{id}

Path parameters

slugstring required

URL-friendly identifier for the entity schema

Example:contact

Entity Type

idstring uuid required

Entity id

Query parameters

string ulid

See https://github.com/ulid/spec

'' | 'null' nullable

Example:01F130Q52Q6MWSNS8N2AVXV4JN

Activity to include in event feed

fill_activityboolean

Update the diff and entity for the custom activity included in the query. Pending state on activity is automatically ended when activity is filled.

asyncboolean

Don't wait for updated entity to become available in Search API. Useful for large migrations

validateboolean

When true, enables entity validation against the entity schema.

directboolean

When true, bypasses changeset interception: attribute values in the payload are written directly to the entity regardless of each attribute's edit_mode. The write always lands, independently of any auto-clear outcome below.

After the direct write, for each attribute in the payload that also has a pending changeset:

edit_mode: external — the incoming value is checked against the changeset's match_strategy (and fuzzy_config when fuzzy). On match, _changesets[attr] is cleared. On no-match, the write still stands and the changeset stays pending (signalling the ERP/trusted source applied a different correction than originally proposed; resolve via a later matching direct write, or via the :apply / :dismiss endpoints).
edit_mode: approval — never auto-cleared. The write lands but the pending changeset remains until explicitly resolved via :apply or :dismiss.

Intended for trusted integrations (e.g. ERP inbound sync). ERP middleware must always use ?direct=true — without it, an inbound sync on an external attribute would create a new changeset instead of confirming the pending one.

Defaults to false — no breaking change for existing callers.

Request body

_idstring uuid

_orgstring

Organization Id the entity belongs to

_schemastring

URL-friendly identifier for the entity schema

_titlestring nullable

Title of entity

_tagsstring[] nullable

_created_atstring date-time nullable

_updated_atstring date-time nullable

_deleted_atstring date-time nullable

_purposestring[] nullable

_purpose_namestring[] nullable

Automatically computed purpose names from _purpose attribute

_manifeststring[] nullable

Manifest ID used to create/update the entity

_changesetsobject nullable

Pending attribute changesets for attributes configured with external or approval edit mode.

The value shape is Changeset (proposed_value, created_at, edit_mode, ...) and is what :apply / :dismiss operate on.

Read-only via normal entity PATCH/PUT operations — those handlers strip _changesets from request bodies. Use the changeset management endpoints to mutate this field.

Example request

{
  "_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "_org": "123",
  "_owners": [
    {
      "org_id": "123",
      "user_id": "123"
    }
  ],
  "_schema": "contact",
  "_tags": [
    "example",
    "mock"
  ],
  "_created_at": "2021-02-09T12:41:43.662Z",
  "_updated_at": "2021-02-09T12:41:43.662Z",
  "_acl": {
    "view": [
      "org:456",
      "org:789"
    ],
    "edit": [
      "org:456"
    ],
    "delete": [
      "org:456"
    ]
  },
  "_manifest": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Response

Success

_idstring uuid required

_orgstring required

Organization Id the entity belongs to

_schemastring required

URL-friendly identifier for the entity schema

_titlestring nullable required

Title of entity

_tagsstring[] nullable

_created_atstring date-time nullable required

_updated_atstring date-time nullable required

_deleted_atstring date-time nullable

_purposestring[] nullable

_purpose_namestring[] nullable

Automatically computed purpose names from _purpose attribute

_manifeststring[] nullable

Manifest ID used to create/update the entity

_changesetsobject nullable

Pending attribute changesets for attributes configured with external or approval edit mode.

The value shape is Changeset (proposed_value, created_at, edit_mode, ...) and is what :apply / :dismiss operate on.

Read-only via normal entity PATCH/PUT operations — those handlers strip _changesets from request bodies. Use the changeset management endpoints to mutate this field.

Example response

{
  "_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "_org": "123",
  "_owners": [
    {
      "org_id": "123",
      "user_id": "123"
    }
  ],
  "_schema": "contact",
  "_tags": [
    "example",
    "mock"
  ],
  "_created_at": "2021-02-09T12:41:43.662Z",
  "_updated_at": "2021-02-09T12:41:43.662Z",
  "_acl": {
    "view": [
      "org:456",
      "org:789"
    ],
    "edit": [
      "org:456"
    ],
    "delete": [
      "org:456"
    ]
  },
  "_manifest": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}