openapi: 3.1.0 info: 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: support@company.com 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: support@company.com 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: johnny@example.com 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: johnny@example.com 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