Delta API: Tracking Changes Over Time

Helpdocs Admin Updated by Helpdocs Admin

The Delta API lets you keep a local copy of a collection in sync with Tokity by repeatedly polling for what's changed, rather than fetching the entire collection every time. It's the recommended approach when you need to synchronize a whole collection or stay notified of the latest changes to one.

Supported Entities

Delta queries are currently available for:

  • Accounts
  • Contacts
  • Agents (users)
  • Tickets
  • Ticket comments
  • Ticket activities
  • Ticket time entries
  • Forms
  • Form results

We'll expose delta query support for additional collections over time, based on customer demand.

Delta Query vs. Webhooks: Which One Should You Use?

Tokity offers both webhooks and delta queries, and they're built for different jobs.

Use webhooks when you need to automate something. Webhooks push events to you in real time, so they're ideal for triggering actions as soon as something happens.

Use delta queries when you need to detect changes reliably or keep data in sync. Delta queries guarantee you'll eventually see every change — even ones you might otherwise miss.

The trade-offs between the two:

Webhooks

Delta Query

Timing

Real-time, event-by-event

Periodic snapshots

Completeness

Captures every individual event, even rapid ones (e.g., a ticket closed and reopened within seconds)

Only shows the latest state since your last check — intermediate changes in between aren't visible

Reliability

Can be missed if your system is down, unless you've built in retries — and even then, retry logic is costly and rare (mostly seen in payment systems)

Very hard to miss changes — if your instance restarts or has an outage, you can simply resume where you left off

Best for

Automation, real-time triggers

Synchronization, change detection

In short: webhooks tell you everything that happened, but can be lost. Delta queries can't tell you the full story of what happened, but they guarantee you'll never lose the current state.

How Delta Query Works

Starting a Delta Query

To begin, call the delta query endpoint for the collection you want, optionally including a startTime:

  • Without startTime — the API walks through the entire collection, treating every item as a "change."
  • With startTime — the API only returns items changed since that point in time.

Paging Through Results

You can't control page size directly — no skip or take parameters here. Instead:

  1. The server returns a batch of changed items.
  2. If more results are available, the response includes a skipToken.
  3. Call the same endpoint again, passing that skipToken, to fetch the next batch.
  4. Repeat until there's no skipToken left in the response — at that point, you've caught up with all current changes.

Staying in Sync Going Forward

Once you've retrieved everything, the final response includes:

  • deltaToken — a marker representing your current sync position
  • retryAfter — how long to wait before checking again

Save both values. When retryAfter has elapsed, call the API again with your saved deltaToken to pick up only what's changed since your last sync.

Don't poll early. If you call the API again before retryAfter has passed, the server will simply tell you to wait — this protects the system from excessive polling.

Handling Deleted Items

Every entity available through the Delta API supports soft delete. When an item has been removed, its response includes a deletedAt property.

If you're synchronizing data locally:

  • Treat any item with deletedAt set as removed in your own system.
  • You can still choose to keep a local copy for reference — just remember that archived items can't be modified again unless they're restored first.

A Note on Hard Deletes

A small number of entities — like tickets — can be permanently (hard) deleted in some cases. When this happens, you will not receive any notification through the Delta API. If your integration depends on knowing about every removal, keep this limitation in mind.

Summary

  • Use delta queries for synchronization and reliable change detection; use webhooks for real-time automation.
  • Start with an optional startTime, page through results using skipToken, and store the final deltaToken and retryAfter for your next sync.
  • Respect retryAfter — polling too soon will just get rejected.
  • Watch for deletedAt to detect soft-deleted items, and be aware that hard deletes are silent.

How did we do?

Webhooks vs. Events — Differences, When to Use Which

Contact