Zendesk Incremental Export API

openapi: 3.2.0
info:
  title: Zendesk Incremental Export API
  version: '1.0'
  description: 'Operations tagged Incremental Export across 4 of this provider''s published API definitions: incremental-openapi-original.yml, organizations-openapi-original.yml, tickets-openapi-original.yml, users-openapi-original.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Incremental Export
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.'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportIncrementalOrganizationsResponse'
              examples:
                default:
                  $ref: '#/components/examples/ExportIncrementalOrganizationsResponseExample'
  /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 in Using the Incremental Exports API

        - Time-based incremental exports in Using the Incremental Exports 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/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 in Using the Incremental Exports API.


        This endpoint supports time-based incremental exports.

        For more information, see Time-based incremental exports in Using the Incremental Exports API. You can also return tickets using cursor-based pagination. See Incremental Ticket Export, Cursor Based.


        The results include tickets that were updated by the system. See

        Excluding system-updated tickets in Using the Incremental Exports 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.

        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. 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 in Using the Incremental Exports 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 in Using the Incremental Exports API.


        #### Allowed For


        * Admins


        #### Sideloading


        See Tickets sideloads. 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.'
      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.'
      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: null
          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
    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: null
        before_url: null
        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: null
          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
    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
    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: null
        before_url: null
        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
x-refined-from:
- incremental-openapi-original.yml
- organizations-openapi-original.yml
- tickets-openapi-original.yml
- users-openapi-original.yml