openapi: 3.1.0 info: title: Helpcenter AgentTimeEntry API version: 1.0.0 tags: - name: AgentTimeEntry paths: /api/v1/agents/{agentId}/timeEntry: get: tags: - AgentTimeEntry summary: List Agent Time Entries description: This API lists the time entries associated with an agent. operationId: getTimeEntryByAgentId parameters: - name: include in: query description: Secondary information related to the time entry. Value supported is @owner@. required: false style: form explode: true schema: type: string description: Secondary information related to the time entry. Value supported is @owner@. enum: - owner - $ref: '#/components/parameters/module' - $ref: '#/components/parameters/departmentId' - name: createdTimeRange in: query description: Key that filters time entries created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z. required: false style: form explode: true schema: type: - string - 'null' description: Key that filters time entries created in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, createdTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z. 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)),(((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))|null - name: limit in: query description: Number of time entries to fetch required: false style: form explode: true schema: type: - string - 'null' - integer format: int32 description: Number of time entries to fetch pattern: ([0-9]+) - $ref: '#/components/parameters/billStatus' - name: orderBy in: query description: Key that sorts the time entries in ascending or descending order, based on the @executedTime@ attribute. Values allowed are @ASC@ (default) and @DESC@. required: false style: form explode: true schema: type: string description: Key that sorts the time entries in ascending or descending order, based on the @executedTime@ attribute. Values allowed are @ASC@ (default) and @DESC@. enum: - ASC - DESC - name: from in: query description: Index number, starting from which the time entries must be fetched required: false style: form explode: true schema: type: - string - integer format: int32 description: Index number, starting from which the time entries must be fetched pattern: ([0-9]+) - name: modifiedTimeRange in: query description: Key that filters time entries whose details were modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z. required: false style: form explode: true schema: type: - string - 'null' description: Key that filters time entries whose details were modified in a particular period of time. Enter the from and to dates in the ISO date format of yyyy-MM-ddThh:mm:ss.SSSZ; for example, modifiedTimeRange=2017-11-05T00:00:00.000Z,2018-09-05T23:59:00.000Z. 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)),(((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))|null - $ref: '#/components/parameters/agentId' - $ref: ./Common.json#/components/parameters/orgId responses: '204': $ref: ./Common.json#/components/responses/emptyResponse '200': $ref: '#/components/responses/getTimeEntryByAgentIdResponse' security: - iam-oauth2-schema: - Desk.settings.READ x-audience: - external-public /api/v1/agents/{agentId}/timeEntrySummation: get: tags: - AgentTimeEntry summary: Get summation of Agent Time Entries description: This API fetches the sum of time entries associated with an agent. operationId: getSummationOfTimeEntryForAgent parameters: - $ref: '#/components/parameters/module' - $ref: '#/components/parameters/departmentId' - $ref: '#/components/parameters/billStatus' - $ref: '#/components/parameters/agentId' - $ref: ./Common.json#/components/parameters/orgId responses: '200': $ref: '#/components/responses/getSummationOfTimeEntryForAgentResponse' security: - iam-oauth2-schema: - Desk.settings.READ x-audience: - external-public /api/v1/agents/{agentId}/timeEntry/{agentTimeEntryId}: get: tags: - AgentTimeEntry summary: Get an Agent Time Entry description: This API fetches a time entry related to an agent. operationId: getTimeEntryForAgent parameters: - name: include in: query description: Secondary information related to the time entry. Value supported is owner. required: false style: form explode: true schema: type: string description: Secondary information related to the time entry. Value supported is owner. enum: - owner - $ref: '#/components/parameters/agentId' - name: agentTimeEntryId 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: '422': $ref: ./Common.json#/components/responses/multipleUnprocessEntityResponse '200': $ref: '#/components/responses/getTimeEntryForAgentResponse' security: - iam-oauth2-schema: - Desk.settings.READ x-audience: - external-public components: responses: getSummationOfTimeEntryForAgentResponse: description: getSummationOfTimeEntryForAgentResponse template definitions content: application/json: schema: type: - 'null' - object additionalProperties: false properties: totalMins: type: - string - 'null' - integer format: int32 pattern: ([0-9]+) totalHours: type: - string - 'null' - integer format: int32 pattern: ([0-9]+) totalCosts: type: - string - 'null' - number pattern: ([0-9\.]+) totalSeconds: type: - string - 'null' - integer format: int32 pattern: ([0-9]+) required: - totalCosts - totalHours - totalMins - totalSeconds examples: Valid responses Definitions: value: totalMins: 5 totalHours: 12 totalCosts: 1000 totalSeconds: 24 getTimeEntryByAgentIdResponse: description: getTimeEntryByAgentIdResponse 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: firstName: type: - string - 'null' maxLength: 50 minLength: 0 lastName: type: - string - 'null' maxLength: 50 minLength: 0 photoURL: type: - string - 'null' maxLength: 100 minLength: 0 pattern: ([0-9a-zA-Z_\-\.\$@\?\,\:\'\/\!\P{InBasicLatin}\s])+ 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: ./AgentTimeEntry.json#/components/schemas/data required: - data examples: Valid responses Definitions: value: data: - owner: firstName: Eswer lastName: KM photoURL: https://contacts.zoho.com/file?t=user&ID=4851669 name: Eswer KM id: '4000000008688129' secondsSpent: '21' parent: ticketNumber: '1001' associatedTicketId: '4000000031007' subject: Task subject id: '4000000031010' type: TASKS executedTime: 1466627400000 fixedCost: null departmentId: '4000000008694' minutesSpent: '23' creatorId: '4000000008692' agentCostPerHour: '3.0' description: Time Entry description hoursSpent: '3' ownerId: '4000000008692' isBillable: true mode: MANUAL isTrashed: 'false' billingType: FIXED_COST_FOR_TICKETS createdTime: 1466061884000 invoiceId: '40000000086881212' id: '4000000033001' requestChargeType: Customer Service additionalCost: '10.0' totalCost: '20.17' - owner: firstName: Eswer lastName: KM photoURL: https://contacts.zoho.com/file?t=user&ID=4851669 name: Eswer KM id: '4000000008688129' secondsSpent: '21' parent: ticketNumber: '1001' associatedTicketId: '4000000031007' subject: Task subject id: '4000000031010' type: TASKS executedTime: 1466796600000 fixedCost: null departmentId: '4000000008694' minutesSpent: '34' creatorId: '4000000008692' agentCostPerHour: '10.0' description: Time Entry description hoursSpent: '3' ownerId: '4000000012090' isBillable: true mode: MANUAL isTrashed: 'false' billingType: FIXED_COST_FOR_TICKETS createdTime: 1466063199000 invoiceId: '40000000086881212' id: '4000000033006' requestChargeType: Product Consultation additionalCost: '10.0' totalCost: '45.72' - owner: firstName: Eswer lastName: KM photoURL: https://contacts.zoho.com/file?t=user&ID=4851669 name: Eswer KM id: '4000000008688129' secondsSpent: '22' parent: ticketNumber: '1001' associatedTicketId: '4000000031007' subject: Task subject id: '4000000031010' type: TASKS executedTime: 1465846200000 fixedCost: null departmentId: '4000000008694' minutesSpent: '22' creatorId: '4000000008692' agentCostPerHour: '20.0' description: Time Entry description hoursSpent: '32' ownerId: '4000000008692' isBillable: true mode: MANUAL isTrashed: 'false' billingType: FIXED_COST_FOR_TICKETS createdTime: 1466063392000 invoiceId: '40000000086881212' id: '4000000033011' requestChargeType: Customer Service additionalCost: '10.0' totalCost: '657.46' getTimeEntryForAgentResponse: description: getTimeEntryForAgentResponse template definitions content: application/json: schema: allOf: - type: object properties: owner: type: - 'null' - object additionalProperties: false maxProperties: 5 minProperties: 5 properties: firstName: type: - string - 'null' maxLength: 50 minLength: 0 lastName: type: - string - 'null' maxLength: 50 minLength: 0 photoURL: type: - string - 'null' maxLength: 100 minLength: 0 pattern: ([0-9a-zA-Z_\-\.\$@\?\,\:\'\/\!\P{InBasicLatin}\s])+ name: type: - string - 'null' maxLength: 50 minLength: 0 id: type: - string - 'null' - integer format: int64 pattern: ([0-9]+) required: - firstName - id - lastName - name - photoURL - oneOf: - additionalProperties: false allOf: - $ref: ./AgentTimeEntry.json#/components/schemas/getTimeEntryForAgentResponse - type: - 'null' - object properties: parent: $ref: ./AgentTimeEntry.json#/components/schemas/getTicketParent required: - parent - additionalProperties: false allOf: - $ref: ./AgentTimeEntry.json#/components/schemas/getTimeEntryForAgentResponse - type: - 'null' - object properties: parent: $ref: ./AgentTimeEntry.json#/components/schemas/getActivityParent required: - parent examples: Valid responses Definitions: value: owner: firstName: Eswer lastName: KM photoURL: https://contacts.zoho.com/file?t=user&ID=4851669 name: Eswer KM id: '4000000008688129' secondsSpent: '21' parent: ticketNumber: '1001' associatedTicketId: '4000000031007' subject: Task subject id: '4000000031010' type: TASKS cf: cf_timeentryname: time1 executedTime: 1466627400000 fixedCost: null departmentId: '4000000008694' minutesSpent: '23' creatorId: '4000000008692' agentCostPerHour: '3.0' description: Time Entry description hoursSpent: '3' ownerId: '4000000008692' isBillable: true mode: MANUAL isTrashed: 'false' billingType: FIXED_COST_FOR_TICKETS createdTime: 1466061884000 invoiceId: '40000000086881212' id: '4000000033001' requestChargeType: Customer Service additionalCost: '10.0' totalCost: '20.17' parameters: module: name: module in: query description: Module from which the time entries must be fetched. Values allowed are @tickets@ and @tasks@. required: false style: form explode: true schema: type: string description: Module from which the time entries must be fetched. Values allowed are @tickets@ and @tasks@. enum: - tickets - tasks - calls - events agentId: name: agentId in: path required: true style: simple explode: false schema: type: - string - 'null' - integer format: int64 pattern: ([0-9]+) billStatus: name: billStatus in: query description: 'Key that filters time entries, based on their billing status: @nonBillable@ , @billable@ or @billed@' required: false style: form explode: true schema: type: string description: 'Key that filters time entries, based on their billing status: @nonBillable@ , @billable@ or @billed@' enum: - nonBillable - billable - billed departmentId: name: departmentId in: query description: ID of the department required: false style: form explode: true schema: type: - string - integer format: int64 description: ID of the department pattern: ([0-9]+) securitySchemes: iam-oauth2-schema: $ref: ./Common.json#/components/securitySchemes/iam-oauth2-schema x-entity: Helpcenter