---
title: "Zendesk Incremental API Migration: Endpoint-by-Endpoint Playbook"
slug: zendesk-incremental-api-migration-endpoint-by-endpoint-playbook
date: 2026-10-05
author: Raajshekhar Rajan
categories: [Zendesk, Help Desk, Migration Guide]
excerpt: "Every deprecated Zendesk Incremental API endpoint mapped to its transactional replacement, with rate-limit math, pagination changes, and working code patterns."
tldr: "Zendesk is cutting third-party access to all /incremental/* endpoints by January 19, 2027. This playbook maps every affected endpoint to its replacement and covers the real engineering trade-offs."
canonical: https://clonepartner.com/blog/zendesk-incremental-api-migration-endpoint-by-endpoint-playbook
---

# Zendesk Incremental API Migration: Endpoint-by-Endpoint Playbook


Zendesk is removing third-party access to every `/api/v2/incremental/*` endpoint between December 2, 2026 and January 19, 2027. Any external data pipeline, ETL process, or migration tool relying on bulk incremental extraction will break unless re-engineered to use standard transactional endpoints.

This playbook is the companion piece to our [overview of the deprecation and who it affects](https://clonepartner.com/blog/blog/zendesk-ending-incremental-apis-for-third-parties-migration-guide). Here we focus on the engineering work: each deprecated endpoint, its replacement, the behavioral differences, and the code-level changes you need to ship.

## Who is affected — and who isn't

**Internal (first-party) integrations are not affected.** Zendesk's announcement is explicit: customers using their own credentials for internal use cases keep full access to incremental endpoints. The restriction targets third-party apps and integrations — whether or not they're listed on the Zendesk Marketplace.

If your app authenticates via OAuth on behalf of Zendesk customers, you need to migrate. If you're an in-house team running scripts under your own Zendesk admin account, nothing changes.

This distinction matters for migration projects. If you rely on a third-party vendor for backups, analytics, or data migration, their tooling will fail silently or degrade if they haven't updated their extraction architecture. At ClonePartner, our custom extraction scripts can execute under the customer's own first-party access when appropriate, ensuring high-volume migrations proceed without hitting transactional bottlenecks.

## Why Zendesk is making this change

**Security.** Incremental APIs are designed for bulk data transfer — a single request returns up to 1,000 records. If a third-party application's credentials are compromised, these endpoints allow rapid, large-scale exfiltration of sensitive customer data. By restricting third-party access to transactional APIs, Zendesk limits the blast radius: transactional endpoints require targeted requests, enforce tighter pagination, and ensure unauthorized activity is smaller in scale and detected faster.

## The complete endpoint remap table

The table below covers every affected endpoint, sourced from [Zendesk's official announcement](https://support.zendesk.com/hc/en-us/articles/11249701485338).

| Deprecated Endpoint | Replacement Endpoint | Notes |
|---|---|---|
| `/api/v2/incremental/tickets/cursor` | `/api/v2/tickets/` | Cursor pagination, `sort=updated_at` |
| `/api/v2/incremental/tickets` | `/api/v2/tickets/` | Same replacement as cursor variant |
| `/api/v2/incremental/users` | `/api/v2/users/` | Cursor pagination, `sort=updated_at` |
| `/api/v2/incremental/users/cursor` | `/api/v2/users/` | Same replacement |
| `/api/v2/incremental/users/sample` | `/api/v2/users/` | Sample endpoint has no direct analog |
| `/api/v2/incremental/organizations` | `/api/v2/organizations` | Standard cursor pagination |
| `/api/v2/incremental/ticket_events` | `/api/v2/ticket_audits` | Different response shape — see below |
| `/api/v2/incremental/ticket_metric_events` | `/api/v2/tickets?include=metric_events` | Sideloaded on ticket list |
| `/api/v2/incremental/ticket_metric_events/count` | `/api/v2/tickets?include=metric_events` | Count derived from sideload |
| `/api/v2/incremental/chats` | `/api/v2/chat/` | Chat API list endpoints |
| `/api/v2/chat/incremental/chats` | `/api/v2/chat/chats` | Chat API list |
| `/api/v2/help_center/incremental/articles` | `/api/v2/help_center/articles` | Standard Help Center list |
| `/api/v2/incremental/custom_objects` | `/api/v2/custom_objects` | Cursor pagination only |
| `/api/v2/incremental/routing/instance_values` | [Skills-based routing API](https://developer.zendesk.com/api-reference/ticketing/ticket-management/skill_based_routing/) | Transactional CRUD |
| `/api/v2/incremental/routing/:param` | Skills-based routing API | Transactional CRUD |
| `/api/v2/incremental/routing/attribute_values` | Skills-based routing API | Transactional CRUD |
| `/api/v2/channels/voice/stats/incremental/calls` | **No alternative** | See Talk section below |
| `/api/v2/channels/voice/stats/incremental/legs` | **No alternative** | See Talk section below |

## What changes when you move to transactional endpoints

The mapping table looks simple. The engineering reality is not. Incremental and transactional APIs behave differently in ways that will break any naive find-and-replace migration.

### Page size drops from 1,000 to 100

**Incremental exports return up to 1,000 records per page.** Standard list endpoints like `/api/v2/tickets/` cap at 100 records per page with cursor pagination — 10× more API calls for the same dataset.

For an account with 500,000 tickets, an incremental export needs roughly 500 paginated requests. The transactional endpoint needs 5,000. This isn't just slower — it burns through your rate-limit budget much faster.

### Rate limits shift from a dedicated bucket to the shared account pool

Incremental exports operate under their own rate-limit bucket: 10 requests per minute (30 with the High Volume API add-on). Standard list endpoints draw from your plan's account-wide limit — 200 requests/minute on Team, 400 on Professional, 700 on Enterprise, and 2,500 on Enterprise Plus or with the High Volume add-on.

The transactional pool looks larger at first glance, but your existing integrations, automations, and agent activity all share it. A full ticket export running at speed can crowd out other API traffic.

> [!WARNING]
> The List Tickets endpoint also carries its own endpoint-specific rate-limit header (`Zendesk-RateLimit-tickets-index`). Watch for both the per-endpoint and account-wide limits in your response headers, and back off on whichever is tighter.

### No native "changed since" filter

This is the biggest architectural difference. The incremental export API accepts a `start_time` parameter and returns only records created or modified after that timestamp. The standard `/api/v2/tickets/` endpoint has no equivalent filter. You get every ticket, every time.

To replicate delta-sync behavior, you have two options:

1. **Sort and bookmark.** Sort by `updated_at`, paginate forward, and stop when you reach records older than your last sync bookmark. This works but introduces edge cases — records updated mid-export can shift position in the sort order, causing duplicates or missed records. Your client must deduplicate by record ID.
2. **Use the Search API.** Supplement with `/api/v2/search.json?query=type:ticket updated>{timestamp}` for time-bound queries. The Search API has its own rate limits and indexing latency, but it gives you native time filtering.

The incremental API also excluded data from the most recent minute to avoid race conditions. With transactional endpoints, building your own buffer window is your responsibility.

### Ticket events → ticket audits: different response shape

The `/api/v2/incremental/ticket_events` endpoint returns a flat stream of events across all tickets. Its replacement, `/api/v2/ticket_audits`, returns audit objects grouped by ticket with a different field structure. As a proposed singer-io/tap-zendesk migration PR [documents](https://github.com/singer-io/tap-zendesk/pull/200), fields would be remapped: `events` becomes `child_events`, `author_id` becomes `updater_id`, and `created_at` becomes `timestamp`.

There's also an **N+1 problem**. Instead of one bulk request yielding thousands of events, extracting audit logs may require querying audits per individual ticket. With 50,000 recently updated tickets, that could mean 50,000 separate API calls — rapidly exhausting your rate limits.

If your downstream consumers depend on the incremental event schema, you need a transformation layer between the new API response and your existing data model.

### Ticket metric events become a sideload

The incremental `ticket_metric_events` endpoint returned metric events as a first-class collection. The replacement is a sideload parameter: `/api/v2/tickets?include=metric_events`. Metric events ride along with ticket responses rather than being independently paginated. If your analytics pipeline consumes metric events as their own entity, you'll need to extract and flatten them from the sideloaded payload.

## Endpoints with no replacement: Talk/Voice data

Two Talk endpoints — `/api/v2/channels/voice/stats/incremental/calls` and `/api/v2/channels/voice/stats/incremental/legs` — have **no alternative endpoint** listed in Zendesk's announcement.

> [!CAUTION]
> There is no transactional endpoint that replicates bulk call/leg export. If your product depends on Talk call data, plan for one of the workarounds below or escalate directly with Zendesk.

Your options:

1. **Run the export under first-party credentials.** If the Zendesk customer authorizes your tool using their own internal admin account (not your third-party OAuth client), incremental access is retained.
2. **Request the 60-day extension.** Starting November 2026, account admins can request a 60-day extension per partner in Admin Center under **Apps & integrations → APIs → API Configuration**.
3. **Use Zendesk Explore or the Talk Partner Edition API.** Explore surfaces Talk metrics via dashboards and scheduled exports. The Talk Partner Edition API provides call object CRUD but is not a bulk export tool.
4. **Accept the data gap.** If your sync focuses on tickets and users, the Talk endpoints may be irrelevant to your core data flow.

## Routing endpoints: migrate to Skills-Based Routing API

The three incremental routing endpoints (`instance_values`, `attribute_values`, and the generic `:param` path) all map to Zendesk's [Skills-based Routing API](https://developer.zendesk.com/api-reference/ticketing/ticket-management/skill_based_routing/). This API provides transactional CRUD for skill types, skill values, and agent-skill assignments — but does **not** support incremental export.

If your integration used the incremental routing endpoints to detect when skills or attribute values changed, you'll need to poll the full list on a schedule and diff against your local state.

## A cursor-pagination pattern for transactional endpoints

Here's a working pattern for paginating through the standard tickets endpoint with cursor pagination, deduplication, and bookmark tracking:

```python
import requests
import time

BASE_URL = "https://{subdomain}.zendesk.com/api/v2"
HEADERS = {"Authorization": "Bearer {access_token}"}

def sync_tickets(last_synced_at: str):
    url = f"{BASE_URL}/tickets.json"
    params = {"page[size]": 100, "sort": "updated_at"}
    seen_ids = set()
    latest_updated = last_synced_at

    while True:
        resp = requests.get(url, headers=HEADERS, params=params)

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue

        resp.raise_for_status()
        data = resp.json()

        for ticket in data["tickets"]:
            if ticket["id"] in seen_ids:
                continue
            seen_ids.add(ticket["id"])

            if ticket["updated_at"] < last_synced_at:
                # Past our bookmark — we've caught up
                return latest_updated

            latest_updated = max(latest_updated, ticket["updated_at"])
            process_ticket(ticket)

        if not data.get("meta", {}).get("has_more", False):
            break

        url = data["links"]["next"]
        params = {}  # params are encoded in the next URL

    return latest_updated
```

This pattern handles **rate-limit backoff** via the `Retry-After` header, **deduplication** using a set of seen IDs (records can shift during pagination), **bookmark tracking** to resume from the last sync point, and **cursor following** via `links.next` until `meta.has_more` is false.

## Data reconciliation and intermediate state

With incremental APIs, the time-ordered nature of responses guaranteed you captured intermediate state changes. Transactional endpoints return the *current* state of a record. If a ticket changes status three times between your polling intervals, the standard ticket endpoint only shows the final status.

If your data warehouse relies on capturing every intermediate state change, you'll need to supplement the API with **Webhooks** for real-time event capture and use the transactional API only for initial historical backfills.

For user syncs, deduplication becomes your responsibility too. Because you can no longer reliably pull "only users modified in the last 5 minutes" without the Search API, your pipeline must handle higher volumes of unchanged records. Your target database should use `external_id` or `email` as an upsert key to prevent duplicate record creation during full-list traversals.

## API tokens are also being retired

Zendesk is simultaneously retiring API tokens as an authentication method. New token creation is blocked from **October 27, 2026**, and all remaining API tokens are permanently deactivated on **April 30, 2027**. If your integration authenticates with `email/token:{api_token}`, you need to migrate to OAuth independently of the incremental API change.

Plan both migrations together. Shipping a new extraction pipeline that still uses API-token auth means you'll be re-deploying again within months.

## Three paths for migration teams

### Path A: First-party credentials

Run the extraction under the customer's own internal Zendesk admin account. Internal use cases retain full incremental access. This is the lowest-friction path for one-time migrations and historical data loads.

### Path B: Re-engineer onto transactional endpoints

Rebuild extraction using cursor-paginated list endpoints with sorting, deduplication, rate-limit handling, and reconciliation logic. This is the only path that works long-term for third-party integrations.

### Path C: 60-day extension

Starting November 2026, account admins can grant your integration a 60-day extension per partner. Navigate to **Admin Center → Apps & integrations → APIs → API Configuration**, select the affected partner, and save. This buys time until March 2027 but doesn't eliminate the migration work.

## Key dates to track

| Date | What Happens |
|---|---|
| September 22, 2026 | Deprecation announced |
| October 27, 2026 | New API token creation blocked |
| November 2026 | 60-day extension requests open in Admin Center |
| December 2, 2026 | Enforcement rollout begins |
| December 17, 2026 – January 4, 2027 | Rollout paused for holidays |
| January 19, 2027 | Enforcement complete — all third-party incremental access blocked |
| April 30, 2027 | All API tokens permanently deactivated |

## What this means for your pipeline

The shift from incremental to transactional endpoints isn't a drop-in swap. It's a re-architecture of your extraction layer. You're moving from an API designed for bulk sync — high page sizes, dedicated rate-limit buckets, built-in change tracking — to general-purpose list endpoints that were never built for that workload.

The work is doable, but it requires careful attention to deduplication, rate-limit management, bookmark logic, and schema transformations. Start now — the December 2 rollout date gives you roughly two months, and the holiday pause doesn't help if your integration breaks on day one.

At ClonePartner, we build custom [Zendesk migration](https://clonepartner.com/blog/help-desk-data-migration/zendesk) extraction scripts per source and target and adapt them when APIs change. We've executed over 1,500 migrations and built 500+ custom integrations, and we've already re-engineered our pipelines for the transactional endpoints. Whether that means utilizing your first-party access for maximum throughput or engineering optimized transactional polling to respect rate limits, we handle the API complexity so your team doesn't have to.

> Need to migrate off Zendesk before the January deadline? ClonePartner builds custom migration scripts that adapt to API changes in real time — no downtime, no data loss. Book a 30-minute call with our engineering team.
>
> [Talk to us](https://clonepartner.com/talk-to-us?duration=30&utm_source=blog&utm_medium=button&utm_campaign=demo_bookings&utm_content=cta_click&utm_term=demo_button_click)

## Frequently asked questions

### Which Zendesk incremental API endpoints are being deprecated?

All /api/v2/incremental/* endpoints are being restricted for third-party developers, including tickets, users, organizations, ticket events, ticket metric events, chats, Help Center articles, custom objects, and routing endpoints. Two Talk endpoints (incremental calls and legs) have no alternative.

### Does the Zendesk incremental API deprecation affect internal integrations?

No. Zendesk's announcement explicitly states that internal (first-party) integrations using the customer's own credentials are unaffected. Only third-party apps and integrations lose access to incremental endpoints.

### What replaces the Zendesk incremental tickets endpoint?

The replacement is /api/v2/tickets/ with cursor pagination, using sort=updated_at to approximate change tracking. Page size drops from 1,000 to 100 records, and there is no native start_time filter — you must implement bookmark and deduplication logic yourself.

### Is there an alternative to the Zendesk Talk incremental calls and legs endpoints?

No. Zendesk lists no alternative endpoint for /api/v2/channels/voice/stats/incremental/calls or /legs. Options include running exports under first-party credentials (which retain incremental access), using Zendesk Explore for reporting, or using the Talk Partner Edition API for individual call records.

### Can I get a deadline extension for the Zendesk incremental API shutdown?

Yes. Starting November 2026, Zendesk account admins can request a 60-day extension per partner in Admin Center under Apps & integrations → APIs → API Configuration. This delays enforcement but doesn't remove the migration requirement.