How to Change an Entity Through the API

Before writing any code, it helps to be clear about what kind of change you're making. The API supports several distinct operations, and picking the right one matters:

• Update a property – change the value of one or more fields on an existing entity.
• Replace an entity – overwrite the entire entity with a new representation (rare, and generally discouraged — see below).
• Delete or archive/deactivate – remove an entity, either permanently or by marking it inactive.
• Restore – bring back a previously archived entity.

Each of these behaves differently depending on the entity type and the API version you're using. This article walks through what to expect from each.

Tracking Changes: lastModifiedAt and lastModifiedBy

Most entities exposed through the API include two fields:

• lastModifiedAt — a timestamp updated whenever the entity changes
• lastModifiedBy — the user or agent who made the change

These are automatically maintained by the system, so you don't need to set them yourself — just be aware they'll reflect the most recent change any time you fetch an entity.

Soft Delete: Archive Instead of Remove

Many entities support soft delete rather than permanent removal. When an entity is soft-deleted, it isn't erased — it's flagged as archived using two properties:

• deletedAt — when the entity was archived
• deletedBy — who archived it

Entities that support soft delete include accounts, contacts, agents, tickets, ticket comments, time entries, and a few others. Settings objects are the exception — they can't be deleted at all.

Why Soft Delete Matters for Delta Queries

Soft delete isn't just about giving users an "undo" option — it's a core part of how delta queries work. When an entity is archived, the system holds off on permanently removing it for a set number of days. This grace period gives any system relying on delta queries time to notice the change and sync accordingly.

Not All Archivable Entities Can Be Hard-Deleted

Some entities — namely accounts, contacts, and agents — can be archived but not permanently deleted. This is because other entities may still reference them. We may introduce true deletion for these in the future, but for now, archiving is as far as it goes.

Updating Properties: It Depends on the API Version

How you update entity properties depends heavily on which API version you're calling.

v2 and v3 (Not Recommended - Deprecated)

These older API versions typically expose updates as POST or PUT requests, which require you to submit all properties to replace the entity or configuration wholesale. A few things to watch out for:

• These endpoints are easy to get wrong — if we add a new property in the future and your request doesn't include it, the system may interpret that as intentional removal.
• To reduce this risk, we try to mark newly added properties as optional and avoid changing them if they weren't specified — but this behavior isn't guaranteed.
• A single logical entity is often split across multiple v2/v3 endpoints, so a single "update" in your integration might only touch part of the entity.

Because of these quirks, we recommend avoiding v2 and v3 for new integrations wherever possible.

v4 (Recommended)

In v4, nearly all entity modifications are exposed as PATCH operations — specifically, merge patch, the same approach used by APIs like Microsoft Graph.

With merge patch:

• You only need to include the properties you want to change.
• The system compares each specified property against its current value and only updates it if it's actually different.
• Properties you don't include are left untouched.

This makes v4 significantly safer and easier to work with than the replace-everything approach in older versions.

Merge Patch Limitations

Merge patch support is strongest for top-level properties. For nested objects (common in settings), some sub-properties may not fully support merge patch — this is uncommon, but worth double-checking if you're working with settings objects.

Collections are a special case. Merge patch doesn't handle collections well — if a property is a list or array, you'll generally need to submit the entire collection to modify or replace it. Order usually doesn't matter, except where the collection's order is meaningful — for example, items within a menu group or service types within a service group.

Denormalized Properties (e.g., Ticket Queue)

Some properties are exposed as denormalized data — meaning they include both an ID and a display name, such as:

{
  "entityId": "12345",
  "name": "Support Queue"
}

In these cases, only entityId is actually used by the server to identify the relationship. The name field is purely for UI display — the server doesn't validate it, so it can technically be set to anything.

Metadata: A Well-Supported Merge Patch Example

The metadata property (typed as Map<string, string>) is a good example of merge patch working well:

• You don't need to send the full metadata map — just the keys you want to change.
• To update a key, provide its new value: { "sample_key": "new value" }
• To remove a key, set its value to null: { "sample_key": null }

Any keys you don't mention are left exactly as they were.

Audit Logs

Most entities keep an audit log that records what changed during a modification — regardless of whether you used PATCH or PUT. The system does its best to detect the actual differences and log only what genuinely changed.

String Comparison Rules

When comparing string values (to determine whether something actually changed), the server:

• Trims leading and trailing whitespace and newlines
• Compares values case-sensitively (ordinal comparison)

Summary

• Decide upfront: are you updating, replacing, deleting, archiving, or restoring?
• Prefer v4 and its merge patch PATCH support — it's safer and easier to use than v2/v3.
• Some entities only support soft delete (archive) — this is intentional and supports delta query syncing.
• Collections and nested settings objects have limited merge patch support — plan accordingly.
• Metadata is a great example of clean, partial-update-friendly design — use null to remove keys.