Zoho TicketTimer API

openapi: 3.1.0
info:
  title: Helpcenter TicketTimer API
  version: 1.0.0
tags:
- name: TicketTimer
paths:
  /api/v1/allActiveTimers:
    get:
      tags:
      - TicketTimer
      summary: List active timers
      description: 'This API lists a particular number of currently active timers in a department, based on the limit specified. '
      operationId: getActiveTimers
      parameters:
      - $ref: '#/components/parameters/departmentId'
      - name: module
        in: query
        description: 'Zoho Desk modules from which the timers must be fetched. Values allowed are: Tickets, Tasks, Events, and Calls. You can pass multiple values by separating them using commas. If you do not pass a value, all modules are considered.'
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: 'Zoho Desk modules from which the timers must be fetched. Values allowed are: Tickets, Tasks, Events, and Calls. You can pass multiple values by separating them using commas. If you do not pass a value, all modules are considered.'
          enum:
          - Tickets
          - Tasks
          maxLength: 100
          minLength: 0
      - $ref: '#/components/parameters/limit'
      - name: startTime
        in: query
        description: 'Point of time before or after which the timers were started. This parameter works in conjunction with the sortBy parameter. If the value of sortBy is startTime, the timers are listed in ascending order. If the value of sortBy is -startTime, they are listed in descending order. (Note: With startTime in play, the time value associated with the last timer in an API response is considered as the value from which the next set of timers must be fetched in the subsequent response.)'
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - integer
          format: int64
          description: 'Point of time before or after which the timers were started. This parameter works in conjunction with the sortBy parameter. If the value of sortBy is startTime, the timers are listed in ascending order. If the value of sortBy is -startTime, they are listed in descending order. (Note: With startTime in play, the time value associated with the last timer in an API response is considered as the value from which the next set of timers must be fetched in the subsequent response.)'
          pattern: ([0-9]+)
      - name: sortBy
        in: query
        description: 'Key that sorts the timers from oldest to latest (ascending order) or latest to oldest (descending order). Values allowed are: startTime (ascending order) and -startTime (descending order, which is the default sorting order). '
        required: false
        style: form
        explode: true
        schema:
          type: string
          description: 'Key that sorts the timers from oldest to latest (ascending order) or latest to oldest (descending order). Values allowed are: startTime (ascending order) and -startTime (descending order, which is the default sorting order). '
          pattern: (-?(startTime))
      - name: owners
        in: query
        description: ' Key that filters timers by Owner. Values allowed are any valid Owner ID or multiple Owner IDs separated by commas.'
        required: false
        style: simple
        explode: true
        schema:
          type: array
          description: ' Key that filters timers by Owner. Values allowed are any valid Owner ID or multiple Owner IDs separated by commas.'
          items:
            type:
            - string
            - integer
            format: int64
            pattern: ([0-9]+)
          uniqueItems: false
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '200':
          $ref: '#/components/responses/getActiveTimers'
      security:
      - iam-oauth2-schema:
        - Desk.tickets.READ
        - Desk.activities.tasks.READ
        - Desk.activities.calls.READ
        - Desk.activities.events.READ
      x-audience:
      - external-public
  /api/v1/tickets/{caseId}/timer:
    get:
      tags:
      - TicketTimer
      summary: Get Ticket Timer
      description: This API fetches the time elapsed in the ticket timer, along with the current state
      operationId: getTicketTimer
      parameters:
      - $ref: '#/components/parameters/caseId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '200':
          $ref: '#/components/responses/ticketTimerJson'
      security:
      - iam-oauth2-schema:
        - Desk.tickets.READ
      x-audience:
      - external-public
    post:
      tags:
      - TicketTimer
      summary: Performs Ticket Timer actions
      description: This API performs timer-related actions, such as START, STOP, PAUSE and RESUME 
      operationId: updateTicketTimerState
      parameters:
      - name: action
        in: query
        description: ' Action of the timer.Supported actions are  @START@, @STOP@, @PAUSE@ and @RESUME@'
        required: true
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: ' Action of the timer.Supported actions are  @START@, @STOP@, @PAUSE@ and @RESUME@'
          enum:
          - START
          maxLength: 100
          minLength: 0
      - $ref: '#/components/parameters/caseId'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '200':
          $ref: '#/components/responses/ticketTimerJson'
      security:
      - iam-oauth2-schema:
        - Desk.tickets.UPDATE
      x-audience:
      - external-public
  /api/v1/myActiveTimers:
    get:
      tags:
      - TicketTimer
      summary: Get Active Timer for an Agent
      description: This API fetches currently running timer details for an agent
      operationId: getMyActiveTimers
      parameters:
      - $ref: '#/components/parameters/departmentId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/from'
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '422':
          $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
        '200':
          $ref: '#/components/responses/getActiveTimerForEntity'
      security:
      - iam-oauth2-schema:
        - Desk.tickets.READ
      x-audience:
      - external-public
  /api/v1/tickets/{entityId}/activeTimer:
    get:
      tags:
      - TicketTimer
      summary: List ticket timers
      description: This API fetches the details of timers currently active in a ticket.
      operationId: getActiveTimersForTicket
      parameters:
      - name: include
        in: query
        description: Secondary information related to the timers. Value supported is @owner@.
        required: false
        style: form
        explode: true
        schema:
          type:
          - string
          - 'null'
          description: Secondary information related to the timers. Value supported is @owner@.
          enum:
          - owner
          maxLength: 100
          minLength: 0
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/from'
      - name: entityId
        in: path
        required: true
        style: simple
        explode: false
        schema:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
      - $ref: ./Common.json#/components/parameters/orgId
      responses:
        '204':
          $ref: ./Common.json#/components/responses/emptyResponse
        '200':
          $ref: '#/components/responses/getActiveTimerForEntity'
      security:
      - iam-oauth2-schema:
        - Desk.tickets.READ
      x-audience:
      - external-public
components:
  parameters:
    from:
      name: from
      in: query
      description: from
      required: false
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int32
        description: from
        pattern: ([0-9]+)
    departmentId:
      name: departmentId
      in: query
      description: ID of the department from which the timers must be fetched
      required: true
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int64
        description: ID of the department from which the timers must be fetched
        pattern: ([0-9]+)
    caseId:
      name: caseId
      in: path
      required: true
      style: simple
      explode: false
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int64
        pattern: ([0-9]+)
    limit:
      name: limit
      in: query
      description: Number of timers to list
      required: false
      style: form
      explode: true
      schema:
        type:
        - string
        - 'null'
        - integer
        format: int32
        description: Number of timers to list
        pattern: ([0-9]+)
  schemas:
    timerJson:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        hours:
          type:
          - 'null'
          - object
          additionalProperties: false
          maxProperties: 3
          minProperties: 3
          properties:
            hours:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
            seconds:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
            minutes:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
          required:
          - hours
          - minutes
          - seconds
        seconds:
          type:
          - 'null'
          - object
          additionalProperties: false
          maxProperties: 3
          minProperties: 3
          properties:
            hours:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
            seconds:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
            minutes:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
          required:
          - hours
          - minutes
          - seconds
        minutes:
          type:
          - 'null'
          - object
          additionalProperties: false
          maxProperties: 3
          minProperties: 3
          properties:
            hours:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
            seconds:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
            minutes:
              type:
              - string
              - 'null'
              maxLength: 100
              minLength: 0
          required:
          - hours
          - minutes
          - seconds
        state:
          type:
          - string
          - 'null'
          enum:
          - RUNNING
          - PAUSED
          - INIT
          maxLength: 100
          minLength: 0
      required:
      - hours
      - minutes
      - seconds
      - state
    ticketWithDueDate:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/ticket'
      - type:
        - 'null'
        - object
        properties:
          dueDate:
            type:
            - string
            - 'null'
            maxLength: 100
            minLength: 0
            pattern: (((19|20)\d\d)[-/.]{1}(0?[1-9]|1[012])[-/.]{1}(0?[1-9]|[12][0-9]|3[01])(T)([01]?[0-9]|2[0-3]):[0-5]?[0-9]:[0-5]?[0-9]([/.][\d]{0,3})?(Z))
        required:
        - dueDate
    getActiveTimersList:
      type:
      - 'null'
      - array
      items:
        oneOf:
        - $ref: '#/components/schemas/ticketActiveTimer'
        - $ref: '#/components/schemas/taskActiveTimer'
        - $ref: '#/components/schemas/taskActiveTimerWithTicket'
    data:
      type:
      - 'null'
      - array
      items:
        oneOf:
        - $ref: '#/components/schemas/ticketTimer'
        - $ref: '#/components/schemas/taskTimer'
        - $ref: '#/components/schemas/ticketTimerWithDueDate'
        - $ref: '#/components/schemas/taskTimerWithDueDate'
    activeTimer:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        owner:
          $ref: '#/components/schemas/actor'
        timer:
          $ref: '#/components/schemas/timerJson'
        startTime:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
        entity:
          type:
          - string
          - 'null'
          enum:
          - Tickets
          - Tasks
          maxLength: 100
          minLength: 0
      required:
      - entity
      - owner
      - startTime
      - timer
    actor:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        photoURL:
          type:
          - string
          - 'null'
          maxLength: 200
          minLength: 0
          pattern: (^(ht|f)tp(s?)\://[-.\w]*(/?)([a-zA-Z0-9\-\.\?\,\:\'/\\+=&%\$#_@]*)?$)
        firstName:
          type:
          - string
          - 'null'
          maxLength: 50
          minLength: 0
        lastName:
          type:
          - string
          - 'null'
          maxLength: 50
          minLength: 0
        name:
          type:
          - string
          - 'null'
          maxLength: 50
          minLength: 0
        id:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
      required:
      - firstName
      - id
      - lastName
      - name
      - photoURL
    taskTimer:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        timer:
          $ref: '#/components/schemas/ticketTimerJson'
        task:
          $ref: '#/components/schemas/task'
        entity:
          type:
          - string
          - 'null'
          enum:
          - Tickets
          - Tasks
          maxLength: 100
          minLength: 0
      required:
      - entity
      - task
      - timer
    ticket:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        ticketNumber:
          type:
          - string
          - 'null'
          - integer
          format: int32
          pattern: ([0-9]+)
        subject:
          type:
          - string
          - 'null'
          maxLength: 1000
          minLength: 0
        depId:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
        id:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
        depName:
          type:
          - string
          - 'null'
          maxLength: 100
          minLength: 0
        status:
          type:
          - string
          - 'null'
          x-dynamic-enum: true
      required:
      - depId
      - depName
      - id
      - status
      - subject
      - ticketNumber
    task:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        subject:
          type:
          - string
          - 'null'
          maxLength: 300
          minLength: 0
        depId:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
        id:
          type:
          - string
          - 'null'
          - integer
          format: int64
          pattern: ([0-9]+)
        depName:
          type:
          - string
          - 'null'
          maxLength: 100
          minLength: 0
        status:
          type:
          - string
          - 'null'
          x-dynamic-enum: true
      required:
      - depId
      - depName
      - id
      - status
      - subject
    taskActiveTimerWithTicket:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/activeTimer'
      - type:
        - 'null'
        - object
        properties:
          task:
            $ref: '#/components/schemas/taskWithDueDate'
          ticket:
            $ref: '#/components/schemas/ticketWithDueDate'
        required:
        - task
        - ticket
    taskTimerWithDueDate:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        timer:
          $ref: '#/components/schemas/ticketTimerJson'
        task:
          $ref: '#/components/schemas/taskWithDueDate'
        entity:
          type:
          - string
          - 'null'
          enum:
          - Tickets
          - Tasks
          maxLength: 100
          minLength: 0
      required:
      - entity
      - task
      - timer
    taskWithDueDate:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/task'
      - type:
        - 'null'
        - object
        properties:
          dueDate:
            type:
            - string
            - 'null'
            maxLength: 100
            minLength: 0
            pattern: (((19|20)\d\d)[-/.]{1}(0?[1-9]|1[012])[-/.]{1}(0?[1-9]|[12][0-9]|3[01])(T)([01]?[0-9]|2[0-3]):[0-5]?[0-9]:[0-5]?[0-9]([/.][\d]{0,3})?(Z))
        required:
        - dueDate
    ticketTimerWithDueDate:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        timer:
          $ref: '#/components/schemas/ticketTimerJson'
        task:
          $ref: '#/components/schemas/taskWithDueDate'
        ticket:
          $ref: '#/components/schemas/ticketWithDueDate'
        entity:
          type:
          - string
          - 'null'
          enum:
          - Tickets
          - Tasks
          maxLength: 100
          minLength: 0
      required:
      - entity
      - task
      - ticket
      - timer
    ticketTimer:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        timer:
          $ref: '#/components/schemas/ticketTimerJson'
        task:
          $ref: '#/components/schemas/task'
        ticket:
          $ref: '#/components/schemas/ticket'
        entity:
          type:
          - string
          - 'null'
          enum:
          - Tickets
          - Tasks
          maxLength: 100
          minLength: 0
      required:
      - entity
      - task
      - ticket
      - timer
    ticketTimerJson:
      type:
      - 'null'
      - object
      additionalProperties: false
      properties:
        hours:
          type:
          - string
          - 'null'
          - integer
          format: int32
          pattern: ([0-9]+)
        seconds:
          type:
          - string
          - 'null'
          - integer
          format: int32
          pattern: ([0-9]+)
        minutes:
          type:
          - string
          - 'null'
          - integer
          format: int32
          pattern: ([0-9]+)
        state:
          type:
          - string
          - 'null'
          enum:
          - RUNNING
          - PAUSED
          - INIT
          maxLength: 100
          minLength: 0
      required:
      - hours
      - minutes
      - seconds
      - state
    ticketActiveTimer:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/activeTimer'
      - type:
        - 'null'
        - object
        properties:
          ticket:
            $ref: '#/components/schemas/ticketWithDueDate'
        required:
        - ticket
    taskActiveTimer:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/activeTimer'
      - type:
        - 'null'
        - object
        properties:
          task:
            $ref: '#/components/schemas/taskWithDueDate'
        required:
        - task
  responses:
    getActiveTimerForEntity:
      description: getActiveTimerForEntity template definitions
      content:
        application/json:
          schema:
            allOf:
            - type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      owner:
                        type:
                        - 'null'
                        - object
                        additionalProperties: false
                        maxProperties: 5
                        minProperties: 5
                        properties:
                          photoURL:
                            type:
                            - string
                            - 'null'
                            maxLength: 100
                            minLength: 0
                            pattern: ([0-9a-zA-Z_\-\.\$@\?\,\:\'\/\!\P{InBasicLatin}\s])+
                          firstName:
                            type:
                            - string
                            - 'null'
                            maxLength: 50
                            minLength: 0
                          lastName:
                            type:
                            - string
                            - 'null'
                            maxLength: 50
                            minLength: 0
                          name:
                            type:
                            - string
                            - 'null'
                            maxLength: 50
                            minLength: 0
                          id:
                            type:
                            - string
                            - 'null'
                            - integer
                            format: int64
                            pattern: ([0-9]+)
                        required:
                        - firstName
                        - id
                        - lastName
                        - name
                        - photoURL
            - type:
              - 'null'
              - object
              additionalProperties: false
              properties:
                data:
                  $ref: '#/components/schemas/data'
              required:
              - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - owner:
                    firstName: Sam
                    lastName: Jones
                    photoURL: https://contacts.zoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20
                    name: Sam Jones
                    id: '7000000020001'
                  timer:
                    hours: 93
                    seconds: 9
                    minutes: 6
                    state: Running
                  userId: '7000000020001'
                - owner:
                    firstName: Robert
                    lastName: Downey
                    photoURL: https://contacts.zoho.com/file?t=user&fs=thumb&ID=56934690&nps=404&exp=20
                    name: Robert Downey
                    id: '7000000030001'
                  timer:
                    hours: 19
                    seconds: 24
                    minutes: 9
                    state: Paused
                  userId: '7000000030001'
    ticketTimerJson:
      description: ticketTimerJson template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              hours:
                type:
                - string
                - 'null'
                - integer
                format: int32
                pattern: ([0-9]+)
              seconds:
                type:
                - string
                - 'null'
                - integer
                format: int32
                pattern: ([0-9]+)
              minutes:
                type:
                - string
                - 'null'
                - integer
                format: int32
                pattern: ([0-9]+)
              state:
                type:
                - string
                - 'null'
                enum:
                - RUNNING
                - PAUSED
                - INIT
                maxLength: 100
                minLength: 0
            required:
            - hours
            - minutes
            - seconds
            - state
          examples:
            Valid responses Definitions:
              value:
                hours: 0
                seconds: 26
                minutes: 5
                state: RUNNING
    getActiveTimers:
      description: getActiveTimers template definitions
      content:
        application/json:
          schema:
            type:
            - 'null'
            - object
            additionalProperties: false
            properties:
              data:
                $ref: '#/components/schemas/getActiveTimersList'
            required:
            - data
          examples:
            Valid responses Definitions:
              value:
                data:
                - owner:
                    firstName: George
                    lastName: McKinson
                    photoURL: https://desk.zoho.com/api/v1/agents/75485000000418459/photo?orgId=60708463
                    name: McKinson George
                    id: '75485000000418459'
                  timer:
                    hours: '137'
                    seconds: '38'
                    minutes: '17'
                    state: RUNNING
                  ticket:
                    ticketNumber: '401'
                    subject: Ticket for timer by another agent
                    dueDate: null
                    depId: '75485000000569047'
                    id: '75485000001513021'
                    depName: TestDept
                    status: Open
                  startTime: '1626290803841'
                  entity: Tickets
                - owner:
                    firstName: Lucas
                    lastName: Carol
                    photoURL: https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463
                    name: Carol Lucas
                    id: '75485000000182033'
                  timer:
                    hours: '192'
                    seconds: '23'
                    minutes: '38'
                    state: RUNNING
                  ticket:
                    ticketNumber: '673'
                    subject: Ticket for timer
                    dueDate: null
                    depId: '75485000000569047'
                    id: '75485000002473027'
                    depName: TestDept
                    status: Open
                  startTime: '1626150959474'
                  entity: Tickets
                - owner:
                    firstName: Lucas
                    lastName: Carol
                    photoURL: https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463
                    name: Carol Lucas
                    id: '75485000000182033'
                  timer:
                    hours: '216'
                    seconds: '10'
                    minutes: '47'
                    state: RUNNING
                  task:
                    subject: Task with ticket for timer
                    dueDate: 1626244200000
                    depId: '75485000000569047'
                    id: '75485000002466025'
                    depName: TestDept
                    status: Not Started
                  ticket:
                    ticketNumber: '672'
                    subject: checking active timer
                    dueDate: 1626244200000
                    depId: '75485000000569047'
                    id: '75485000002459023'
                    depName: TestDept
                    status: Open
                  startTime: '1626064031778'
                  entity: Tasks
                - owner:
                    firstName: Lucas
                    lastName: Carol
                    photoURL: https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463
                    name: Carol Lucas
                    id: '75485000000182033'
                  timer:
                    hours: '226'
                    seconds: '21'
                    minutes: '21'
                    state: RUNNING
                  startTime: '1626029581045'
                  event:
                    subject: 'Event without ticket '
                    dueDate: null
                    depId: '75485000000569047'
                    id: '75485000002463059'
                    depName: TestDept
                    status: Not Started
                  entity: Events
                - owner:
                    firstName: Lucas
                    lastName: Carol
                    photoURL: https://desk.zoho.com/api/v1/agents/75485000000182033/photo?orgId=60708463
                    name: Carol Lucas
                    id: '75485000000182033'
                  timer:
                    hours: '274'
                    seconds: '42'
                    minutes: '26'
                    state: RUNNING
                  task:
                    subject: Task without ticket
                    dueDate: null
                    depId: '75485000000569047'
                    id: '75485000000572019'
                    depName: TestDept
                    status: Not Started
                  startTime: '1625856459759'
                  entity: Tasks
  securitySchemes:
    iam-oauth2-schema:
      $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema
x-entity: Helpcenter