The Zendesk Incremental API lets you export only the records that have changed since a specific point in time, making it easy to keep external systems in sync without repeatedly pulling full datasets. It supports core objects such as tickets, users, organizations, and ticket events, returning results in chronological order along with a checkpoint (an end_time or a cursor) you store and use on your next request to continue exactly where you left off.
openapi: 3.1.0
info:
version: "1.0"
title: Zendesk Incremental
description: Needs a description.
paths:
/api/v2/incremental/{incremental_resource}/sample:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
- $ref: '#/components/parameters/IncrementalResource'
get:
operationId: IncrementalSampleExport
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Incremental_resource Sample
description: >
Use this endpoint to test the incremental export format. It's more
strict in terms of rate limiting,
at 10 requests per 20 minutes instead of 10 requests per minute. It also
returns only up to 50
results per request. Otherwise, it's identical to the above APIs.
Use the `incremental_resource` parameter to specify the resource.
Possible values are "tickets", "ticket_events", "users", or
"organizations".
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TimeBasedExportIncrementalTicketsResponse'
examples:
default:
$ref: >-
#/components/examples/TimeBasedExportIncrementalTicketsResponseExample
/api/v2/incremental/organizations:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
- $ref: '#/components/parameters/IncrementalPage'
get:
operationId: IncrementalOrganizationExport
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Organizations
description: >
#### Allowed For
* Admins
#### Sideloading
See [Organizations
sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ExportIncrementalOrganizationsResponse'
examples:
default:
$ref: >-
#/components/examples/ExportIncrementalOrganizationsResponseExample
/api/v2/incremental/routing/attribute_values:
get:
operationId: IncrementalSkilBasedRoutingAttributeValuesExport
tags:
- Incremental Skill Based Routing
summary: Zendesk Get Api V2 Incremental Routing Attribute_values
description: >
Returns a stream of changes that occurred on routing attribute values.
#### Allowed For
* Admins
#### Parameters
Optional
| Name | Type | Comment
| ------ | ------ | -------
| cursor | string | The `cursor` parameter is a non-human-readable
argument you can use to move forward or backward in time. The cursor is
a read-only URL parameter that's only available in API responses. See
[Pagination](#pagination).
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/IncrementalSkillBasedRouting'
examples:
default:
$ref: >-
#/components/examples/IncrementalSkillBasedRoutingAttributeValuesExample
/api/v2/incremental/routing/attributes:
get:
operationId: IncrementalSkilBasedRoutingAttributesExport
tags:
- Incremental Skill Based Routing
summary: Zendesk Get Api V2 Incremental Routing Attributes
description: >
Returns a stream of changes that occurred on routing attributes.
#### Allowed For
* Admins
#### Parameters
Optional
| Name | Type | Comment
| ------ | ------ | -------
| cursor | string | The `cursor` parameter is a non-human-readable
argument you can use to move forward or backward in time. The cursor is
a read-only URL parameter that's only available in API responses. See
[Pagination](#pagination).
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/IncrementalSkillBasedRouting'
examples:
default:
$ref: >-
#/components/examples/IncrementalSkillBasedRoutingAttributesExample
/api/v2/incremental/routing/instance_values:
get:
operationId: IncrementalSkilBasedRoutingInstanceValuesExport
tags:
- Incremental Skill Based Routing
summary: Zendesk Get Api V2 Incremental Routing Instance_values
description: >
Returns a stream of changes that occurred on routing instance values.
Changes are grouped by `attribute_value_id`,
with associate type events listed alongside unassociate type events
based on the unassociate event’s timestamp.
#### Allowed For
* Admins
#### Parameters
Optional
| Name | Type | Comment
| ------ | ------ | -------
| cursor | string | The `cursor` parameter is a non-human-readable
argument you can use to move forward or backward in time. The cursor is
a read-only URL parameter that's only available in API responses. See
[Pagination](#pagination).
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/IncrementalSkillBasedRouting'
examples:
default:
$ref: >-
#/components/examples/IncrementalSkillBasedRoutingInstanceValuesExample
/api/v2/incremental/ticket_events:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
get:
operationId: IncrementalTicketEvents
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Ticket_events
description: >
Returns a stream of changes that occurred on tickets, excluding events
occuring within one minute of the request. Each event is tied
to an update on a ticket and contains all the fields that were updated
in that
change. For more information, see:
- [Exporting ticket
events](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-ticket-events)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api)
- [Time-based incremental
exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api)
You can include comments in the event stream by using the
`comment_events`
sideload. See Sideloading below. If you don't specify the sideload, any
comment
present in the ticket update is described only by Boolean
`comment_present`
and `comment_public` object properties in the event's `child_events`
array.
The comment itself is not included.
#### Allowed For
* Admins
#### Sideloading
The endpoint supports the `comment_events` sideload. Any comment present
in the ticket
update is listed as an object in the event's `child_events` array.
Example:
```js
"child_events": [
{
"id": 91048994488,
"via": {
"channel": "api",
"source": {"from":{},"to":{},"rel":null}},
"via_reference_id":null,
"type": "Comment",
"author_id": 5031726587,
"body": "This is a comment",
"html_body": "<div class="zd-comment"><p dir="auto">This is a comment</p>",
"public": true,
"attachments": [],
"audit_id": 91048994468,
"created_at": "2009-06-25T10:15:18Z",
"event_type": "Comment"
},
...
],
...
```
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/ExportIncrementalTicketEventsResponse'
examples:
default:
$ref: >-
#/components/examples/ExportIncrementalTicketEventsResponseExample
/api/v2/incremental/ticket_metric_events:
get:
operationId: ListTicketMetricEvents
tags:
- Ticket Metric Events
summary: Zendesk Get Api V2 Incremental Ticket_metric_events
description: >-
Returns ticket metric events that occurred on or after the start time.
Cursor pagination returns a maximum of 100 records per page. Events are
listed in chronological order.
If the results are not paginated, events will be returned as a
time-based incremental export.
See [Time-based incremental
exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports).
#### Pagination
* Cursor pagination
See [Pagination](/api-reference/introduction/pagination/).
#### Allowed For
* Admins
parameters:
- name: start_time
in: query
description: >-
The Unix UTC epoch time of the oldest event you're interested in.
Example: 1332034771.
required: true
schema:
type: integer
example: 1332034771
- name: include_changes
in: query
description: >-
This optional parameter enhances incremental data retrieval,
delivering a consistent and accurate representation of data changes.
schema:
type: boolean
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/TicketMetricEventsResponse'
examples:
default:
$ref: '#/components/examples/TicketMetricEventsResponseExample'
/api/v2/incremental/tickets:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
get:
operationId: IncrementalTicketExportTime
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Tickets
description: >
Returns the tickets that changed since the start time. For more
information,
see [Exporting
tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
This endpoint supports time-based incremental exports.
For more information, see [Time-based incremental
exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#time-based-incremental-exports)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
You can also return tickets using cursor-based pagination. See
[Incremental Ticket Export, Cursor
Based](#incremental-ticket-export-cursor-based).
The results include tickets that were updated by the system. See
[Excluding system-updated
tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#excluding-system-updated-tickets-time-based-exports)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
The endpoint can return tickets with an `updated_at` time that's earlier
than the
`start_time` time. The reason is that the API compares the `start_time`
with the ticket's
`generated_timestamp` value, not its `updated_at` value. The
`updated_at` value is
updated only if the update generates a [ticket
event](#incremental-ticket-event-export).
The `generated_timestamp` value is updated for all ticket updates,
including system
updates. If a system update occurs after a ticket event, the unchanged
`updated_at` time will become earlier relative to the updated
`generated_timestamp`
time.
#### Allowed For
* Admins
#### Sideloading
See [Tickets
sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).
For performance reasons,
`last_audits` sideloads aren't supported.
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TimeBasedExportIncrementalTicketsResponse'
examples:
default:
$ref: >-
#/components/examples/TimeBasedExportIncrementalTicketsResponseExample
/api/v2/incremental/tickets/cursor:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
- $ref: '#/components/parameters/IncrementalCursor'
get:
operationId: IncrementalTicketExportCursor
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Tickets Cursor
description: >
Returns the tickets that changed since the start time. For more
information,
see [Exporting
tickets](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#exporting-tickets)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
This endpoint supports cursor-based incremental exports.
Cursor-based exports are highly encouraged because they provide more
consistent performance and
response body sizes. For more information, see [Cursor-based incremental
exports](/documentation/ticketing/managing-tickets/using-the-incremental-export-api#cursor-based-incremental-exports)
in [Using the Incremental Exports
API](/documentation/ticketing/managing-tickets/using-the-incremental-export-api).
#### Allowed For
* Admins
#### Sideloading
See [Tickets
sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).
For performance reasons,
`last_audits` sideloads aren't supported.
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: >-
#/components/schemas/CursorBasedExportIncrementalTicketsResponse
examples:
default:
$ref: >-
#/components/examples/CursorBasedExportIncrementalTicketsResponseExample
/api/v2/incremental/users:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
- $ref: '#/components/parameters/IncrementalPage'
get:
operationId: IncrementalUserExportTime
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Users
description: >
#### Allowed For
* Admins
#### Sideloading
See [Users
sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/TimeBasedExportIncrementalUsersResponse'
examples:
default:
$ref: >-
#/components/examples/TimeBasedExportIncrementalUsersResponseExample
/api/v2/incremental/users/cursor:
parameters:
- $ref: '#/components/parameters/IncrementalUnixTime'
- $ref: '#/components/parameters/IncrementalCursor'
- $ref: '#/components/parameters/IncrementalPage'
get:
operationId: IncrementalUserExportCursor
tags:
- Incremental Export
summary: Zendesk Get Api V2 Incremental Users Cursor
description: >
#### Allowed For
* Admins
#### Sideloading
See [Users
sideloads](/documentation/ticketing/using-the-zendesk-api/side_loading/#supported-endpoints).
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CursorBasedExportIncrementalUsersResponse'
examples:
default:
$ref: >-
#/components/examples/CursorBasedExportIncrementalUsersResponseExample
components:
schemas:
TimeBasedExportIncrementalTicketsResponse:
type: object
description: >
See [Tickets](/api-reference/ticketing/tickets/tickets/) for a detailed
example.
properties:
count:
type: integer
end_of_stream:
type: boolean
end_time:
type: integer
next_page:
type: string
nullable: true
tickets:
type: array
items:
$ref: '#/components/schemas/TicketObject'
example:
count: 2
end_of_stream: true
end_time: 1390362485
next_page: >-
https://{subdomain}.zendesk.com/api/v2/incremental/tickets.json?per_page=3&start_time=1390362485
tickets:
- assignee_id: 235323
collaborator_ids:
- 35334
- 234
created_at: '2009-07-20T22:55:29Z'
custom_fields:
- id: 27642
value: '745'
- id: 27648
value: 'yes'
description: The fire is very colorful.
due_at:
external_id: ahg35h3jh
follower_ids:
- 35334
- 234
generated_timestamp: 1304553600
group_id: 98738
has_incidents: false
id: 35436
organization_id: 509974
priority: high
problem_id: 9873764
raw_subject: '{{dc.printer_on_fire}}'
recipient: [email protected]
requester_id: 20978392
satisfaction_rating:
comment: Great support!
id: 1234
score: good
sharing_agreement_ids:
- 84432
status: open
subject: Help, my printer is on fire!
submitter_id: 76872
tags:
- enterprise
- other_tag
type: incident
updated_at: '2011-05-05T10:38:52Z'
url: https://company.zendesk.com/api/v2/tickets/35436.json
via:
channel: web
ExportIncrementalOrganizationsResponse:
type: object
properties:
count:
type: integer
end_of_stream:
type: boolean
end_time:
type: integer
next_page:
type: string
nullable: true
organizations:
type: array
items:
$ref: '#/components/schemas/OrganizationObject'
example:
count: 1
end_of_stream: true
end_time: 1601357503
next_page: >-
https://example.zendesk.com/api/v2/incremental/ticket_events.json?start_time=1601357503
organizations:
- created_at: '2018-11-14T00:14:52Z'
details: caterpillar =)
domain_names:
- remain.com
external_id: ABC198
group_id: 1835962
id: 4112492
name: Groablet Enterprises
notes: donkey
organization_fields:
datepudding: '2018-11-04T00:00:00+00:00'
org_field_1: happy happy
org_field_2: teapot_kettle
shared_comments: false
shared_tickets: false
tags:
- smiley
- teapot_kettle
updated_at: '2018-11-14T00:54:22Z'
url: https://example.zendesk.com/api/v2/organizations/4112492.json
IncrementalSkillBasedRouting:
title: Incremental Skill-based Routing
type: object
properties:
attribute_values:
type: array
description: Routing attribute values
items:
$ref: '#/components/schemas/IncrementalSkillBasedRoutingAttributeValue'
attributes:
type: array
description: Routing attributes
items:
$ref: '#/components/schemas/IncrementalSkillBasedRoutingAttribute'
count:
type: integer
description: The number of results returned for the current request
readOnly: true
end_time:
type: integer
description: >-
The most recent resource creation time present in this result set in
Unix epoch time
readOnly: true
instance_values:
type: array
description: Routing instance values
items:
$ref: '#/components/schemas/IncrementalSkillBasedRoutingInstanceValue'
next_page:
type: string
description: The URL that should be called to get the next set of results
readOnly: true
ExportIncrementalTicketEventsResponse:
type: object
properties:
count:
type: integer
end_of_stream:
type: boolean
end_time:
type: integer
next_page:
type: string
nullable: true
ticket_events:
type: array
items:
$ref: '#/components/schemas/TicketMetricEventBaseObject'
example:
count: 1
end_of_stream: true
end_time: 1601357503
next_page: >-
https://example.zendesk.com/api/v2/incremental/ticket_events.json?start_time=1601357503
ticket_events:
- id: 926256957613
instance_id: 1
metric: agent_work_time
ticket_id: 155
time: '2020-10-26T12:53:12Z'
type: measure
TicketMetricEventsResponse:
type: object
allOf:
- type: object
properties:
ticket_metric_events:
type: array
items:
$ref: '#/components/schemas/TicketMetricEventBaseObject'
- type: object
properties:
count:
type: integer
end_time:
type: integer
next_page:
type: string
CursorBasedExportIncrementalTicketsResponse:
type: object
description: >
See [Tickets](/api-reference/ticketing/tickets/tickets/) for a detailed
example.
properties:
after_cursor:
type: string
nullable: true
after_url:
type: string
nullable: true
before_cursor:
type: string
nullable: true
before_url:
type: string
nullable: true
end_of_stream:
type: boolean
tickets:
type: array
items:
$ref: '#/components/schemas/TicketObject'
example:
after_cursor: MTU3NjYxMzUzOS4wfHw0Njd8
after_url: >-
https://{subdomain}.zendesk.com/api/v2/incremental/tickets/cursor.json?cursor=MTU3NjYxMzUzOS4wfHw0Njd8
before_cursor:
before_url:
end_of_stream: true
tickets:
- assignee_id: 235323
collaborator_ids:
- 35334
- 234
created_at: '2009-07-20T22:55:29Z'
custom_fields:
- id: 27642
value: '745'
- id: 27648
value: 'yes'
description: The fire is very colorful.
due_at:
external_id: ahg35h3jh
follower_ids:
- 35334
- 234
generated_timestamp: 1304553600
group_id: 98738
has_incidents: false
id: 35436
organization_id: 509974
priority: high
problem_id: 9873764
raw_subject: '{{dc.printer_on_fire}}'
recipient: [email protected]
requester_id: 20978392
satisfaction_rating:
comment: Great support!
id: 1234
score: good
sharing_agreement_ids:
- 84432
status: open
subject: Help, my printer is on fire!
submitter_id: 76872
tags:
- enterprise
- other_tag
type: incident
updated_at: '2011-05-05T10:38:52Z'
url: https://company.zendesk.com/api/v2/tickets/35436.json
via:
channel: web
TimeBasedExportIncrementalUsersResponse:
type: object
properties:
count:
type: integer
end_of_stream:
type: boolean
end_time:
type: integer
next_page:
type: string
nullable: true
users:
type: array
items:
$ref: '#/components/schemas/UserObject'
example:
count: 1
end_of_stream: true
end_time: 1601357503
next_page: >-
https://example.zendesk.com/api/v2/incremental/ticket_events.json?start_time=1601357503
users:
- active: true
alias: Mr. Johnny
created_at: '2009-07-20T22:55:29Z'
custom_role_id: 9373643
details: ''
email: [email protected]
external_id: sai989sur98w9
id: 35436
last_login_at: '2011-05-05T10:38:52Z'
locale: en-US
locale_id: 1
moderator: true
name: Johnny Agent
notes: Johnny is a nice guy!
only_private_comments: false
organization_id: 57542
phone: '+15551234567'
photo:
content_type: image/png
content_url: https://company.zendesk.com/photos/my_funny_profile_pic.png
id: 928374
name: my_funny_profile_pic.png
size: 166144
thumbnails:
- content_type: image/png
content_url: >-
https://company.zendesk.com/photos/my_funny_profile_pic_thumb.png
id: 928375
name: my_funny_profile_pic_thumb.png
size: 58298
restricted_agent: true
role: agent
role_type: 0
shared: false
shared_agent: false
signature: Have a nice day, Johnny
suspended: true
tags:
- enterprise
- other_tag
ticket_restriction: assigned
time_zone: Copenhagen
updated_at: '2011-05-05T10:38:52Z'
url: https://company.zendesk.com/api/v2/users/35436.json
user_fields:
user_date: '2012-07-23T00:00:00Z'
user_decimal: 5.1
user_dropdown: option_1
verified: true
CursorBasedExportIncrementalUsersResponse:
type: object
properties:
after_cursor:
type: string
nullable: true
after_url:
type: string
nullable: true
before_cursor:
type: string
nullable: true
before_url:
type: string
nullable: true
end_of_stream:
type: boolean
users:
type: array
items:
$ref: '#/components/schemas/UserObject'
example:
after_cursor: MTU3NjYxMzUzOS4wfHw0Njd8
after_url: >-
https://example.zendesk.com/api/v2/incremental/users/cursor.json?cursor=MTU3NjYxMzUzOS4wfHw0Njd8
before_cursor:
before_url:
end_of_stream: true
users:
- active: true
alias: Mr. Johnny
created_at: '2009-07-20T22:55:29Z'
custom_role_id: 9373643
details: ''
email: [email protected]
external_id: sai989sur98w9
id: 35436
last_login_at: '2011-05-05T10:38:52Z'
locale: en-US
locale_id: 1
moderator: true
name: Johnny Agent
notes: Johnny is a nice guy!
only_private_comments: false
organization_id: 57542
phone: '+15551234567'
photo:
content_type: image/png
content_url: https://company.zendesk.com/photos/my_funny_profile_pic.png
id: 928374
name: my_funny_profile_pic.png
size: 166144
thumbnails:
- content_type: image/png
content_url: >-
https://company.zendesk.com/photos/my_funny_profile_pic_thumb.png
id: 928375
name: my_funny_profile_pic_thumb.png
size: 58298
restricted_agent: true
role: agent
role_type: 0
shared: false
shared_agent: false
signature: Have a nice day, Johnny
suspended: true
tags:
- enterprise
- other_tag
ticket_restriction: assigned
time_zone: Copenhagen
updated_at: '2011-05-05T10:38:52Z'
url: https://company.zendesk.com/api/v2/users/35436.json
user_fields:
user_date: '2012-07-23T00:00:00Z'
user_decimal: 5.1
user_dropdown: option_1
verified: true
tags:
- name: Incremental Export
- name: Incremental Skill Based Routing
- name: Ticket Metric Events