Sign in

v4

latestOpenAPI 3.0.22026-07-3188146256.6 KB
Entities

upsertEntity

Create or update an entity using unique_key

  • If no entities are matched, a new entity is created.
  • If exactly one entity is matched, a PATCH-style update is applied to the existing entity.

Activity

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

patch/v1/entity/{slug}:upsert

Path parameters

slugstring required

URL-friendly identifier for the entity schema

Example:contact

Entity Type

Query parameters

string ulid

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

OR
'' | '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.

dry_runboolean

Dry Run mode = return results but does not perform the operation.

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.

strictboolean

Strict mode = return 409 if more than one entity is matched

Request body

unique_keystring[] required

Example request

{
  "unique_key": [
    "_id"
  ],
  "entity": {
    "_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

Entity was updated

_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"
  ]
}