openapi: 3.0.3

info:
  title: Time Entries
  description: "For retrieving and updating time entries. For information of how to construct requests utilising fieldsets, sorting, paging, filters, and '*includes*', please refer to the API Developer Portal. E&OE."
  version: "1.0"

externalDocs:
  description: API Developer Portal - Constructing API Requests
  url: https://docs.actionstep.com/api-requests/

paths:
  '/timeentries':
    get:
      description: Returns a collection of time entries.
      tags:
        - Time Entries
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedTimeEntries'

    post:
      description: Create a new time entry.
      tags:
        - Time Entries
      requestBody:
        $ref: '#/components/requestBodies/CreateTimeEntry'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'

  '/timeentries/{id}':
    get:
      description: Returns a single time entry.
      tags:
        - Time Entries
      parameters:
        - name: id
          in: path
          description: Unique identifier for a time entry.
          required: true
          schema:
            type: integer
            format: int32
          example: 9287
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'

    put:
      description: Update a time entry.
      tags:
        - Time Entries
      parameters:
        - name: id
          in: path
          description: Unique identifier for a time entry.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      requestBody:
        $ref: '#/components/requestBodies/UpdateTimeEntry'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeEntry'

    delete:
      description: Delete a time entry.
      tags:
        - Time Entries
      parameters:
        - name: id
          in: path
          description: Unique identifier for a time entry.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      responses:
        '204':
          description: Success, No Content.

components:
  schemas:
    PagedTimeEntries:
      type: object
      properties:
        timeentries:
          type: array
          items:
            $ref: '#/components/schemas/TimeEntry'
        meta:
          $ref: '#/components/schemas/PageMetaData'

    PageMetaData:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingData'

    PagingData:
      type: object
      properties:
        timeentries:
          $ref: '#/components/schemas/TimeEntriesPageData'

    TimeEntriesPageData:
      type: object
      properties:
        recordCount:
          description: The total number of time entries returned by the underlying query.
          type: integer
          example: 2487
        pageCount:
          description: The total number of pages generated by the underlying query.
          type: integer
          example: 50
        page:
          description: The page number for this page of time entries.
          type: integer
          example: 2
        pageSize:
          description: Page size.
          type: integer
          example: 50
        prevPage:
          description: A URL to the previous page of time entries.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/timeentries?page=1
        nextPage:
          description: A URL to the next page of time entries.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/timeentries?page=3

    TimeEntry:
      type: object
      properties:
        id:
          description: Unique identifier for the time entry.
          example: 47
          type: integer
        timestampDate:
          description: The date for the time entry.
          example: 2022-05-03T00:00:00+12:00
          format: timestamp
          type: string
        description:
          description: Description for the time entry.
          example: Court hearing
          type: string
        actualHours:
          description: Number of hours spent on the time entry.
          example: 2.50
          type: number
          multipleOf: 0.01
        billableHours:
          description: Number of billable hours for the time entry.
          example: 2.50
          type: number
          multipleOf: 0.01
        createdTimestamp:
          description: Date and time the time entry was created.
          example: 2022-05-03T20:06:29+12:00
          format: timestamp
          type: string
        startTime:
          description: Time when work on the time entry started.
          example: 09:00:00
          format: time
          type: string
        timerStatus:
          description: Status of the recording timer.
          enum:
            - Running
            - Paused
            - Stopped
            - Locked
          example: Stopped
          type: string
        timerStartedClientTimestamp:
          description: Time stamp when the client timer was started.
          example: 2022-05-03T20:06:29+12:00
          format: timestamp
          type: string
        timerDurationSeconds:
          description: Duration of the timer measured in seconds.
          example: 9000
          type: integer
          format: string
        billingBehavior:
          description: Billing behavior for the time entry.
          enum:
            - Bill
            - Hide
            - No charge
          example: Bill
          type: string
        rateUnitPrice:
          description: Unit price for each billable time unit (typically per hour).
          example: 750.00
          type: number
          multipleOf: 0.01
        rateSource:
          description: Source of the rate unit price.
          enum:
            - Default
            - Timekeeper
            - Action
            - Participant
            - Custom
            - Bulk custom rate
          example: Timekeeper
          format: string
        rateTimestamp:
          description: Deprecated property.
          example: null
          type: string
        billableAmountType:
          description: How the billable amount is derived.
          enum:
            - Fixed
            - Calculated
          example: Calculated
          type: string
        billableAmount:
          description: Billable amount for the time entry.
          example: 1875.00
          type: number
          multipleOf: 0.01
        isBillable:
          description: Indicates if the time entry is billable.
          enum:
            - T
            - F
          example: T
          type: string
        importExternalReference:
          description: Used when importing data into Actionstep from a third-party data source.
          example: DDH-3838939-333
          type: string
        links:
          $ref: '#/components/schemas/TimeEntryLinks'

    TimeEntryLinks:
      type: object
      properties:
        task:
          description: Unique identifier for the task to which the time entry is associated.
          type: integer
          format: string
          example: 29339
        quickCode:
          description: Unique identifier to the quick code for the time entry.
          type: integer
          format: string
          example: 273
        createdBy:
          description: Actionstep user who created the time entry.
          type: integer
          format: string
          example: 12
        owner:
          description: Actionstep user who owns and is responsible for this time entry.
          type: integer
          format: string
          example: 14
        action:
          description: Unique identifier of the matter to which the time entry is associated.
          type: integer
          format: string
          example: 7334
        rate:
          description: Unique identifier of the rate table entry applicable to the time entry.
          type: integer
          format: string
          example: 17
        utbmsActivityCode:
          description: UTBMS activity code for the time entry.
          example: A120
          type: string
        utbmsTaskCode:
          description: UTBMS task code for the time entry.
          example: X50
          type: string
        utbmsTimekeeperCode:
          description: UTBMS code for the timekeeper associated with the time entry.
          example: TK830
          type: string
        phoneRecord:
          description: Phone record associated with the time entry.
          type: integer
          format: string
          example: 1176

    CreateTimeEntry:
      type: object
      required:
        - timestampDate
        - actualHours
        - createdBy
        - owner
      properties:
        timestampDate:
          description: The date for the time entry.
          example: 2022-05-03T00:00:00+12:00
          format: timestamp
          type: string
        description:
          description: Description for the time entry.
          example: Court hearing
          type: string
        actualHours:
          description: Number of hours spent on the time entry.
          example: 2.50
          type: number
          multipleOf: 0.01
        billableHours:
          description: Number of billable hours for the time entry.
          example: 2.50
          type: number
          multipleOf: 0.01
        createdTimestamp:
          description: Date and time the time entry was created.
          example: 2022-05-03T20:06:29+12:00
          format: timestamp
          type: string
        startTime:
          description: Time when work on the time entry started.
          example: 09:00:00
          format: time
          type: string
        timerStatus:
          description: Status of the recording timer.
          enum:
            - Running
            - Paused
            - Stopped
            - Locked
          example: Stopped
          type: string
        timerStartedClientTimestamp:
          description: Time stamp when the client timer was started.
          example: 2022-05-03T20:06:29+12:00
          format: timestamp
          type: string
        timerDurationSeconds:
          description: Duration of the timer measured in seconds.
          example: 9000
          type: integer
          format: string
        billingBehavior:
          description: Billing behavior for the time entry.
          enum:
            - Bill
            - Hide
            - No charge
          example: Bill
          type: string
        rateUnitPrice:
          description: Unit price for each billable time unit (typically per hour).
          example: 750.00
          type: number
          multipleOf: 0.01
        rateSource:
          description: Source of the rate unit price.
          enum:
            - Default
            - Timekeeper
            - Action
            - Participant
            - Custom
            - Bulk custom rate
          example: Timekeeper
          format: string
        rateTimestamp:
          description: Deprecated property.
          example: null
          type: string
        billableAmountType:
          description: How the billable amount is derived.
          enum:
            - Fixed
            - Calculated
          example: Calculated
          type: string
        billableAmount:
          description: Billable amount for the time entry.
          example: 1875.00
          type: number
          multipleOf: 0.01
        isBillable:
          description: Indicates if the time entry is billable.
          enum:
            - T
            - F
          example: T
          type: string
        importExternalReference:
          description: Used when importing data into Actionstep from a third-party data source.
          example: DDH-3838939-333
          type: string
        links:
          $ref: '#/components/schemas/CreateTimeEntryLinks'

    CreateTimeEntryLinks:
      type: object
      properties:
        task:
          description: Unique identifier for the task to which the time entry is associated.
          type: integer
          format: string
          example: 29339
        quickCode:
          description: Unique identifier to the quick code for the time entry.
          type: integer
          format: string
          example: 273
        createdBy:
          description: Actionstep user who created the time entry.
          type: integer
          format: string
          example: 12
        owner:
          description: Actionstep user who owns and is responsible for this time entry.
          type: integer
          format: string
          example: 14
        action:
          description: Unique identifier of the matter to which the time entry is associated.
          type: integer
          format: string
          example: 7334
        rate:
          description: Unique identifier of the rate table entry applicable to the time entry.
          type: integer
          format: string
          example: 17
        utbmsActivityCode:
          description: UTBMS activity code for the time entry.
          example: A120
          type: string
        utbmsTaskCode:
          description: UTBMS task code for the time entry.
          example: X50
          type: string
        utbmsTimekeeperCode:
          description: UTBMS code for the timekeeper associated with the time entry.
          example: TK830
          type: string
        phoneRecord:
          description: Phone record associated with the time entry.
          type: integer
          format: string
          example: 1176

    UpdateTimeEntry:
      type: object
      required:
        - timestampDate
        - actualHours
        - createdBy
        - owner
      properties:
        timestampDate:
          description: The date for the time entry.
          example: 2022-05-03T00:00:00+12:00
          format: timestamp
          type: string
        description:
          description: Description for the time entry.
          example: Court hearing
          type: string
        actualHours:
          description: Number of hours spent on the time entry.
          example: 2.50
          type: number
          multipleOf: 0.01
        billableHours:
          description: Number of billable hours for the time entry.
          example: 2.50
          type: number
          multipleOf: 0.01
        createdTimestamp:
          description: Date and time the time entry was created.
          example: 2022-05-03T20:06:29+12:00
          format: timestamp
          type: string
        startTime:
          description: Time when work on the time entry started.
          example: 09:00:00
          format: time
          type: string
        timerStatus:
          description: Status of the recording timer.
          enum:
            - Running
            - Paused
            - Stopped
            - Locked
          example: Stopped
          type: string
        timerStartedClientTimestamp:
          description: Time stamp when the client timer was started.
          example: 2022-05-03T20:06:29+12:00
          format: timestamp
          type: string
        timerDurationSeconds:
          description: Duration of the timer measured in seconds.
          example: 9000
          type: integer
          format: string
        billingBehavior:
          description: Billing behavior for the time entry.
          enum:
            - Bill
            - Hide
            - No charge
          example: Bill
          type: string
        rateUnitPrice:
          description: Unit price for each billable time unit (typically per hour).
          example: 750.00
          type: number
          multipleOf: 0.01
        rateSource:
          description: Source of the rate unit price.
          enum:
            - Default
            - Timekeeper
            - Action
            - Participant
            - Custom
            - Bulk custom rate
          example: Timekeeper
          format: string
        rateTimestamp:
          description: Deprecated property.
          example: null
          type: string
        billableAmountType:
          description: How the billable amount is derived.
          enum:
            - Fixed
            - Calculated
          example: Calculated
          type: string
        billableAmount:
          description: Billable amount for the time entry.
          example: 1875.00
          type: number
          multipleOf: 0.01
        isBillable:
          description: Indicates if the time entry is billable.
          enum:
            - T
            - F
          example: T
          type: string
        importExternalReference:
          description: Used when importing data into Actionstep from a third-party data source.
          example: DDH-3838939-333
          type: string
        links:
          $ref: '#/components/schemas/UpdateTimeEntryLinks'

    UpdateTimeEntryLinks:
      type: object
      properties:
        task:
          description: Unique identifier for the task to which the time entry is associated.
          type: integer
          format: string
          example: 29339
        quickCode:
          description: Unique identifier to the quick code for the time entry.
          type: integer
          format: string
          example: 273
        createdBy:
          description: Actionstep user who created the time entry.
          type: integer
          format: string
          example: 12
        owner:
          description: Actionstep user who owns and is responsible for this time entry.
          type: integer
          format: string
          example: 14
        action:
          description: Unique identifier of the matter to which the time entry is associated.
          type: integer
          format: string
          example: 7334
        rate:
          description: Unique identifier of the rate table entry applicable to the time entry.
          type: integer
          format: string
          example: 17
        utbmsActivityCode:
          description: UTBMS activity code for the time entry.
          example: A120
          type: string
        utbmsTaskCode:
          description: UTBMS task code for the time entry.
          example: X50
          type: string
        utbmsTimekeeperCode:
          description: UTBMS code for the timekeeper associated with the time entry.
          example: TK830
          type: string
        phoneRecord:
          description: Phone record associated with the time entry.
          type: integer
          format: string
          example: 1176

  requestBodies:
    CreateTimeEntry:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateTimeEntry'

    UpdateTimeEntry:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateTimeEntry'