Migrating third-party integrations from incremental APIs
For security reasons, third-party developers, apps, and integrations will no longer have access to the affected incremental APIs. The change applies to third-party integrations whether or not they are listed in the Zendesk Marketplace.
You need to update your integration if it calls one or more of the affected incremental APIs. This includes:
- Marketplace apps
- Non-Marketplace integrations
- Partner-operated integrations
- Integrations that call Zendesk APIs on behalf of a Zendesk customer
No action is required if your integration does not use an affected incremental API.
Migration requirements
Replacing an incremental API URL with an alternative endpoint may not preserve identical behavior. Incremental APIs provide specific synchronization capabilities that might not be available in standard alternative APIs.
Before migrating, review the alternative API documentation and confirm how your integration will handle:
- Pagination
- Cursor support
- Timestamp filtering
- Change tracking
- Event semantics
- Event ordering
- Deleted records
- Historical data availability
- Response formats
- Rate limits
You may need to update your integration’s:
- Synchronization logic
- Pagination logic
- Checkpointing or timestamp tracking
- Deduplication logic
- Retry logic
- Error handling
- Deleted-record handling
Test the updated integration with representative Zendesk data before deploying it to production.
Affected endpoints and migration options
The following table lists the affected Incremental endpoints and possible alternatives. The alternatives provide access to related resource data, but they are not necessarily one-to-one replacements.
Choose an alternative based on the data and synchronization requirements of your integration.
| Affected endpoint | Product or resource | Possible alternative |
|---|---|---|
| /api/v2/incremental/chats | Chat | /api/v2/chat/ (See Chats) |
| /api/v2/incremental/ticket_events | Support | /api/v2/ticket_audits (See Ticket Audits) |
| /api/v2/incremental/ticket_metric_events | Support | /api/v2/tickets?include=metric_events (See Supported Endpoints) |
| /api/v2/incremental/tickets/cursor | Support | /api/v2/tickets (See Tickets) |
| /api/v2/incremental/tickets | Support | /api/v2/tickets (See Tickets) |
| /api/v2/incremental/users | Support | /api/v2/users (See Users) |
| /api/v2/incremental/users/cursor | Support | /api/v2/users (See Users) |
| /api/v2/incremental/routing/instance_values | Routing | See Skills-based Routing APIs |
| /api/v2/incremental/routing/{param} | Routing | See Skills-based Routing APIs |
| /api/v2/incremental/routing/attribute_values | Routing | See Skills-based Routing APIs |
| /api/v2/incremental/organizations | Support | /api/v2/organizations (See Organizations) |
| /api/v2/incremental/ticket_metric_events/count | Support | /api/v2/tickets?include=metric_events (See Supported Endpoints) |
| /api/v2/incremental/users/sample | Support | /api/v2/users (See Users) |
| /api/v2/channels/voice/stats/incremental/calls | Talk | No alternative endpoint |
| /api/v2/channels/voice/stats/incremental/legs | Talk | No alternative endpoint |
| /api/v2/help_center/incremental/articles | Help Center | /api/v2/help_center/articles (See Articles) |
| /api/v2/chat/incremental/chats | Chat | /api/v2/chat/chats (See Chats) |
| /api/v2/incremental/custom_objects | Custom Objects | /api/v2/custom_objects (See Custom Objects) |
Recommended migration process
Identifying affected API calls
Search your integration’s source code, configuration, and logs for the affected endpoint paths.
Also check whether an SDK, library, or third-party service used by your integration calls an affected endpoint indirectly.
Reviewing the alternative API
Confirm that the alternative API provides the data required by your integration. Pay particular attention to differences in:
- Available filters
- Pagination model
- Response structure
- Data completeness
- Ordering
- Rate limits
- Required permissions or scopes
Updating synchronization logic
Incremental APIs are designed to help integrations retrieve changes over time. An alternative resource or collection endpoint may require you to implement or modify:
- A timestamp-based synchronization strategy
- Cursor or offset pagination
- Checkpoint storage
- Duplicate detection
- Retry and resume behavior
- Handling for records that are updated or deleted
Testing the migration
Test the updated integration using:
- Multiple pages of results
- Records created and updated during synchronization
- Duplicate or retried requests
- Deleted records, if applicable
- Rate-limit responses
- Temporary API errors
- Empty result sets
- Large data sets