Optibus Work Entities API

openapi: 3.0.0
info:
  title: Optibus Operations Driver Absences Work Entities API
  version: 2.8.17
  description: '**Welcome to the Optibus Operations API documentation!**


    Optibus Operations is a cloud-based software solution that enables public transport providers to optimize their operations, planning, and scheduling. Our API provides programmatic access to Optibus Operations'' functionality, allowing you to integrate it with your own applications and systems.



    '
  license:
    name: Optibus Ltd, All rights reserved
  contact: {}
servers:
- url: https://YOUR-OPTIBUS-ACCOUNT.api.ops.optibus.co
  description: Contact your Optibus Customer Success Manager for the actual baseURL and API credentials to use.
tags:
- name: Work Entities
paths:
  /v2/work-entities:
    get:
      operationId: GetWorkEntities
      responses:
        '200':
          description: WorkEntities Informantion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkEntitiesResponse'
        '413':
          description: The request is too long. Please reduce the number of drivers or days.
      description: 'Retrieves workEntities values for depots within a specified date range and for specified driver IDs or by depotId.

        There is a limit of 204k work-entities calculation per request to avoid timeouts. This limit enables, for example,

        a calculation of 100 drivers for 30 days with 100 daily work-entities defined. In case the limit is exceeded, a 413 error code will be returned, together with the allowed amount of drivers for the existing configuration.'
      summary: List work entities
      tags:
      - Work Entities
      security:
      - api_key: []
      parameters:
      - description: '- Optional. The ID of a specific depot for which workEntities are to be retrieved.'
        in: query
        name: depotId
        required: false
        schema:
          $ref: '#/components/schemas/DepotId'
      - description: '- Optional. An array of driver IDs for whom workEntities are to be retrieved.'
        in: query
        name: driverIds
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/DriverUuid'
      - description: '- The start date of the workEntities period.'
        in: query
        name: startDate
        required: false
        schema:
          $ref: '#/components/schemas/StringifyDate'
      - description: '- The end date of the workEntities period.'
        in: query
        name: endDate
        required: false
        schema:
          $ref: '#/components/schemas/StringifyDate'
      - description: '- Optional. If true, all workEntities will be exported, regardless of the configuration.'
        in: query
        name: exportAllEntities
        required: false
        schema:
          type: boolean
      - description: '- Optional. Will attempt to retreive the data from the cache if true. If false, will always calculate the data.'
        in: query
        name: shouldUseCache
        required: false
        schema:
          type: boolean
  /v2/calculation-limit:
    get:
      operationId: GetAPICalculationLimit
      responses:
        '200':
          description: Work-engine APIs calculation limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAPICalculationLimitResponse'
      description: 'Fetches the maximum number of drivers allowed per API request for the given dates for a particular client.

        To prevent timeouts, there is a cap of 204000 work-entity calculations per request. This cap allows, for instance,

        the calculation of 100 drivers over a 30-day period with 100 daily work-entities specified.


        The `mode` parameter controls which flow''s cost model is used to compute the limit:

        - `payroll` (default): the limit accounts for payroll cycle boundaries that may extend the effective date range beyond what was requested. This is the safe default — it always returns a limit `<=` the `workEntities` limit, so it can never exceed what `/v2/payroll` will accept. Use this when calling `/v2/payroll`.

        - `workEntities`: the limit is based on the exact requested date range. Opt into this when calling `/v2/work-entities`.'
      summary: Fetch work engine API calculation limit
      tags:
      - Work Entities
      security:
      - api_key: []
      parameters:
      - description: '- The start date of the calculation period.'
        in: query
        name: startDate
        required: false
        schema:
          $ref: '#/components/schemas/StringifyDate'
      - description: '- The end date of the calculation period.'
        in: query
        name: endDate
        required: false
        schema:
          $ref: '#/components/schemas/StringifyDate'
      - description: '- Optional. The flow for which to compute the limit (`payroll` or `workEntities`). Defaults to `payroll`.'
        in: query
        name: mode
        required: false
        schema:
          $ref: '#/components/schemas/CalculationLimitMode'
components:
  schemas:
    GetAPICalculationLimitResponse:
      properties:
        limit:
          type: number
          format: double
      required:
      - limit
      type: object
    WorkEntityExternal:
      properties:
        timeType:
          $ref: '#/components/schemas/_TimeType'
        result:
          $ref: '#/components/schemas/WorkEntityAPIValues'
        entityId:
          $ref: '#/components/schemas/WorkEntityId'
        occurrenceDates:
          properties:
            endDate:
              $ref: '#/components/schemas/StringifyDate'
            startDate:
              $ref: '#/components/schemas/StringifyDate'
          required:
          - endDate
          - startDate
          type: object
        workingDriver:
          $ref: '#/components/schemas/WorkingDriver'
        depotId:
          $ref: '#/components/schemas/DepotId'
      required:
      - timeType
      - result
      - entityId
      - occurrenceDates
      - workingDriver
      - depotId
      type: object
    WorkEntityId:
      type: string
    DepotId:
      $ref: '#/components/schemas/UUID'
      description: The depot unique identifier in the Ops system.
    WorkEntitiesAPIValueTypesEnum.Distance:
      enum:
      - Distance
      type: string
    _TimeType:
      anyOf:
      - $ref: '#/components/schemas/_TimeTypeDay'
      - $ref: '#/components/schemas/TimeTypeWeeks'
      - $ref: '#/components/schemas/_TimeTypeCycle'
      - $ref: '#/components/schemas/_TimeTypeDynamic'
    TimeTypeKind.Cycle:
      enum:
      - cycle
      type: string
    UUID:
      type: string
      description: Stringified ID for a resource. Cannot exceed 36 characters.
    GetWorkEntitiesResponse:
      items:
        $ref: '#/components/schemas/WorkEntityExternal'
      type: array
    TimeTypeKind.Dynamic:
      enum:
      - dynamic
      type: string
    WorkEntityBooleanValue:
      properties:
        value:
          type: boolean
        type:
          $ref: '#/components/schemas/WorkEntitiesAPIValueTypesEnum.Boolean'
      required:
      - value
      - type
      type: object
    WorkEntityNumberValue:
      properties:
        value:
          type: number
          format: double
        type:
          $ref: '#/components/schemas/WorkEntitiesAPIValueTypesEnum.Number'
      required:
      - value
      - type
      type: object
    CycleType:
      enum:
      - weekly
      - biWeekly
      - monthly
      type: string
    ISOWithTimeDate:
      type: string
      format: date
      description: Stringified ISO8601 date in the form of 2017-07-21T23:59:00+03:00
    _TimeTypeDay:
      properties:
        type:
          $ref: '#/components/schemas/TimeTypeKind.Day'
      required:
      - type
      type: object
    DriverUuid:
      $ref: '#/components/schemas/UUID'
      description: The driver unique identifier in the Ops system (not the driver personal id)
    WorkEntitiesAPIValueTypesEnum.Boolean:
      enum:
      - Boolean
      type: string
    WorkEntitiesAPIValueTypesEnum.TimeIntervals:
      enum:
      - timeInterval
      type: string
    WorkEntityDistanceValue:
      properties:
        value:
          type: number
          format: double
        type:
          $ref: '#/components/schemas/WorkEntitiesAPIValueTypesEnum.Distance'
      required:
      - value
      - type
      type: object
    WorkingDriver:
      properties:
        driverExternalId:
          type: string
        driverUuid:
          $ref: '#/components/schemas/DriverUuid'
      required:
      - driverExternalId
      - driverUuid
      type: object
    WorkEntityDurationInMinutesValue:
      properties:
        value:
          $ref: '#/components/schemas/Minutes'
        type:
          $ref: '#/components/schemas/WorkEntitiesAPIValueTypesEnum.DurationInMinutes'
      required:
      - value
      - type
      type: object
    _TimeTypeCycle:
      properties:
        cycleType:
          $ref: '#/components/schemas/CycleType'
        type:
          $ref: '#/components/schemas/TimeTypeKind.Cycle'
      required:
      - cycleType
      - type
      type: object
    TimeTypeWeeks:
      properties:
        count:
          type: number
          format: double
        type:
          $ref: '#/components/schemas/TimeTypeKind.Weeks'
      required:
      - count
      - type
      type: object
    Minutes:
      type: integer
      format: int32
      description: time measure in minutes
    WorkEntitiesAPIValueTypesEnum.DurationInMinutes:
      enum:
      - durationInMinutes
      type: string
    WorkEntityAPIValues:
      anyOf:
      - $ref: '#/components/schemas/WorkEntityBooleanValue'
      - $ref: '#/components/schemas/WorkEntityDurationInMinutesValue'
      - $ref: '#/components/schemas/WorkEntityIntervalsValue'
      - $ref: '#/components/schemas/WorkEntityNumberValue'
      - $ref: '#/components/schemas/WorkEntityErrorValue'
      - $ref: '#/components/schemas/WorkEntityDistanceValue'
    WorkEntitiesAPIValueTypesEnum.Error:
      enum:
      - error
      type: string
    CalculationLimitMode:
      enum:
      - payroll
      - workEntities
      type: string
    _TimeTypeDynamic:
      properties:
        type:
          $ref: '#/components/schemas/TimeTypeKind.Dynamic'
      required:
      - type
      type: object
    WorkEntitiesAPIValueTypesEnum.Number:
      enum:
      - Number
      type: string
    TimeTypeKind.Weeks:
      enum:
      - weeks
      type: string
    WorkEntityIntervalsValue:
      properties:
        value:
          $ref: '#/components/schemas/ApiTimeInterval'
        type:
          $ref: '#/components/schemas/WorkEntitiesAPIValueTypesEnum.TimeIntervals'
      required:
      - value
      - type
      type: object
    StringifyDate:
      type: string
      format: date
      description: Stringified ISO8601 date in the form of `YYYY-MM-dd`, for example `2017-07-21`
    ApiTimeInterval:
      items:
        properties:
          end:
            $ref: '#/components/schemas/ISOWithTimeDate'
          start:
            $ref: '#/components/schemas/ISOWithTimeDate'
        required:
        - end
        - start
        type: object
      type: array
    WorkEntityErrorValue:
      properties:
        value:
          type: string
        type:
          $ref: '#/components/schemas/WorkEntitiesAPIValueTypesEnum.Error'
      required:
      - value
      - type
      type: object
    TimeTypeKind.Day:
      enum:
      - day
      type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
x-tagGroups:
- name: General API Info
  tags:
  - Authentication
  - Versioning
- name: Use case guides
  tags:
  - HR System Integration Guides
  - Fleet Management System Integration Guides
  - Operational Plan Query Guides
  - Custom Driver App Notification Action Guide
- name: Client preferences
  tags:
  - Preferences
- name: Resource Management
  tags:
  - Regions
  - Drivers
  - Driver Absences
  - Driver Employment Periods
  - Driver Custom Attributes
  - Driver Groups
  - Vehicles
  - Vehicle Downtimes
  - Vehicle Custom Attributes
- name: Operations Management
  tags:
  - Roster
  - Operational Plan
  - Tasks
  - Stops
  - Signing Times
- name: Work & Payroll
  tags:
  - Work Entities
  - Payroll
  - Statistics
- name: Private Hires
  tags:
  - Private Hires
- name: Driver App Integration
  tags:
  - Driver App Notifications
- name: Event Webhooks
  tags:
  - Event Webhooks
- name: Data Ingestion
  tags:
  - Tacho Ingestion
- name: Deprecated API Endpoints
  tags:
  - Drivers (Deprecated)
  - Vehicles (Deprecated)
  - Operational Plan (Deprecated)
- name: Changelog
  tags:
  - Changelog