Optibus Operations API (2.8.1)

The Optibus Operations API requires authentication via a stable API_KEY sent in the HTTP request Authorization header in the form of Authorization: API_KEY. Additionally requests against our API expect the X-Optibus-Api-Client header to be set using your ACCOUNT_NAME.

If you are considering programmatic access the Optibus Operations platform, please contact your Optibus Customer Success Manager who can provide the API_KEY and ACCOUNT_NAME above, as well as your account-specific BASE_URL for the API endpoints documented below.

Example:

CURL -H "Authorization:API_KEY" -H 'X-Optibus-Api-Client: API_USER' https://BASE_URL/driver

We may in the future make changes to the Optibus Operations API described on this page. This could be to fix bugs, enhance the richness of information made available in existing endpoints, or to introduce new API functionality via new endpoints.

The Optibus Operations team treats API changes in the following way:

• we follow Semantic Versioning for the version number of the overall API as documented on this page. Individual endpoints may be provided with versions indicated as prefix such as /v{version}/{endpoint}. These endpoint specific numbers may lag behind the major version of the overall API, but will never exceed it.
• we will NOT change existing API endpoints in a breaking way suddently. Breaking changes in this sense would be to
  • remove previously documented endpoints
  • remove previously documented properties in responses
  • change the type of documented properties in responses (e.g. number to string, or YYYY-MM-DD string to proper ISOtime string)
  • remove or change documented request parameters for endpoints
  • add new required request parameters to existing endpoints
• we MAY without considering this a breaking change
  • add additional properties to response objects
  • add additional optional request parameters (e.g. new filtering options)
  • add new endpoints

In case we do introduce breaking changes to existing endpoints, this will happen in the following way:

• we will add a new version of the affected endpoint, prepended with a version prefix with an increased version number. E.g. if we would make a breaking change to {baseURL}/v1/driver, we would introduce a new endpoint {baseURL}/v2/driver with adjusted behavior
• may deprecate the old endpoint. We will wait at least 3 months after announcing such a change on this page before shutting down the deprecated endpoint
• may consider the announcement of deprecation of an endpoint as a major change to the overall API version (as indicated in the title of this document) and increase the version number accordingly

This section gives step-by-step guides for common integration scenarios with external HR systems. For help with your particular integration scenario, please contact your Optibus Customer Success Manager.

This use case details how to create and update driver information in Optibus when changes are made in your external HR system.

Process:

1. Driver Creation in External HR System:

   When a new driver is created in your HR system, make a POST request to the /v2/drivers API endpoint.

   Example Request:

   POST /v2/drivers
   Authorization: <YOUR_API_TOKEN>
   Content-Type: application/json
   
   {
     "drivers": [
       {
         "id": "driver-id-001",
         "firstName": "John",
         "lastName": "Smith",
         "regionName": "North Region",
         "startDate": "2024-01-15",
         "emailAddress": "john.smith@example.com"
       }
     ]
   }
   

   Notes:

   • Each request is atomic - either all drivers are created successfully, or none are created.
   • Maximum 1000 drivers per request.
   • If startDate is provided, an initial employment period will be created automatically.
   • We recommend using the ID of the driver in the external HR system as the id field in the request, so that the driver has the same identifier in both of your systems.

2. Driver Modification in External HR System:

   When an existing driver is edited in your HR system, make a PUT request to the /v2/drivers API endpoint.

   Example Request:

   PUT /v2/drivers
   Authorization: <YOUR_API_TOKEN>
   Content-Type: application/json
   
   {
     "drivers": [
       {
         "id": "driver-id-001",
         "firstName": "John",
         "lastName": "Smith-Jones",
         "emailAddress": "john.smithjones@example.com",
         "customAttributes": {
           "licenseNumber": "DL123456"
         }
       }
     ]
   }
   

   Notes:

   • This endpoint expects a full representation of the driver - omitting optional fields will clear them.
   • Maximum 1000 drivers per request.
   • PUT does not support startDate, regionName, depotName, or groupName fields.

This use case describes how to regularly update an external HR system with driver information from Optibus using a recurring job (e.g., a cron job).

Process:

1. Fetch Drivers from Optibus:

   Make a GET request to the /v2/drivers API endpoint. The response is paginated.

   Example Request:

   GET /v2/drivers?page=1&isEmployed=true
   Authorization: <YOUR_API_TOKEN>
   

   Example Response:

   {
     "drivers": [
       {
         "id": "driver-id-001",
         "firstName": "John",
         "lastName": "Smith",
         "emailAddress": "john.smith@example.com",
         "mainRegionPeriod": {
           "regionName": "North Region",
           "depotName": "Main Depot"
         },
         "customAttributes": {
           "licenseNumber": "DL123456"
         }
       }
     ],
     "pagination": {
       "currentPage": 1,
       "totalPages": 5
     }
   }
   

2. Process Drivers:

   • For each driver in the drivers array, create or update the corresponding record in your HR system using the driver's id as the identifier.
   • If pagination.currentPage < pagination.totalPages, increment the page parameter and repeat until all pages are processed.

This use case details how to reflect changes made to driver absences in an external HR system within Optibus.

Process:

1. Absence Creation in External HR System:

   • When a new absence is created in your HR system:
     • Assign a unique identifier to this absence. We recommend using UUIDs (Universally Unique Identifiers).
     • Make a POST request to the /v1/absences API endpoint.
     • The request body must be an array containing one or more absence objects. For a single creation, this will be an array with one element. Each absence object should include the unique absenceId, code (absence type), driverId, startDate, startTime, endDate, and endTime. Refer to the API documentation for the full list of required and optional parameters per absence object.
     • Note: times are represented as minutes from midnight (e.g., 540 = 09:00, 1020 = 17:00), in the local timezone of your operation.

   Example POST Request Body for Creating an Absence:

   [
     {
       "absenceId": "your-new-unique-uuid-string",
       "driverId": "driver-id-789",
       "code": "PERSONAL",
       "startDate": "2024-02-01",
       "startTime": 600, // 10:00
       "endDate": "2024-02-01",
       "endTime": 720, // 12:00
       "notes": "Personal appointment"
     }
   ]
   

   API Call:

   POST /v1/absences
   Authorization: <YOUR_API_TOKEN>
   Content-Type: application/json
   
   // Request body from above (array containing the absence object)
   

2. Absence Modification in External HR System:

   • When an existing absence is edited in your HR system (e.g., change in dates, absence type):
     • Make a POST request to the /v1/absences endpoint in the Optibus API. This endpoint handles updates (upserts) for absences.
     • Crucially, ensure you use the same absenceId as the original absence.
     • The request body must be an array containing the absence object(s) to be updated.
     • Update the relevant fields within the absence object, such as code, startDate, startTime, endDate, and endTime, as needed.
     • Note: times are represented as minutes from midnight (e.g., 540 = 09:00, 1020 = 17:00), in the local timezone of your operation.

   Example POST Request Body for Updating an Absence: (Note the absenceId is the same as an existing absence in Optibus)

   [
     {
       "absenceId": "your-existing-unique-uuid-string",
       "driverId": "driver-id-789",
       "code": "SICK",
       "startDate": "2024-02-01",
       "startTime": 600, // 10:00
       "endDate": "2024-02-02",
       "endTime": 720, // 12:00
       "notes": "Updated: Doctor's appointment, extended"
     }
   ]
   

   API Call:

   POST /v1/absences
   Authorization: <YOUR_API_TOKEN>
   Content-Type: application/json
   
   // Request body from above (array containing the updated absence object)
   

   • Note on Changing Assigned Driver: The Optibus API does not currently support changing the driverId for an existing absence directly through an update. If a driver assignment needs to be changed for an absence:

     1. The original absence must be deleted from Optibus. See "Absence Deletion" below.
     2. A new absence record must be created with a new unique absenceId and the correct driverId using the creation process described above (sent in an array).

   • Balance Validation: When the entitlementBanksEffectiveDate feature flag is enabled, the API validates that absences do not cause negative balance violations for entitlement banks that do not allow negative balances. If violations are detected, the API returns HTTP 422 with details about which drivers have violations and which banks are affected.

     • You can skip balance validation by adding the query parameter skipBalanceValidation=true to your request (e.g., POST /v1/absences?skipBalanceValidation=true).
     • The HTTP 422 error can only occur when ALL of the following conditions are met:
       1. The entitlementBanksEffectiveDate feature flag is enabled
       2. Entitlement banks are configured and do NOT allow negative balances
       3. The driver has entitlements
       4. The absence is connected to the bank (by absence type)
       5. The driver would violate the balance constraints (would cause negative balance)
       6. The skipBalanceValidation query parameter is NOT set to "true" (validation is enabled by default)

     Example HTTP 422 Error Response:

     {
       "error": {
         "type": "negativeBalanceViolation",
         "message": "One or more absences would cause negative balance violations",
         "details": {
           "drivers": [
             {
               "driverId": "driver-id-123",
               "violatedBanks": ["Vacation", "Sick"]
             },
             {
               "driverId": "driver-id-456",
               "violatedBanks": ["Vacation"]
             }
           ],
           "summary": {
             "affectedDrivers": 2
           }
         }
       }
     }
     

3. Absence Deletion in External HR System:

   • When an absence is deleted from your HR system:
     • The Optibus API does not currently support the direct deletion of absences via an API endpoint.
     • Please contact Optibus if you require this functionality in the API.

This use case describes how to regularly update an external HR system with driver absence data from Optibus. This is typically achieved by setting up a recurring job (e.g., a cron job).

Process:

1. Schedule a Recurring Job:

   • Configure a cron job or a similar scheduled task to run at a desired frequency (e.g., every X hours, or once per day).

2. Fetch Driver Absences from Optibus:

   • The job should make a GET request to the /v2/drivers/absences API endpoint.
   • The API response is paginated and includes an array of absence objects.
   • Note: times are represented as minutes from midnight (e.g., 540 = 09:00, 1020 = 17:00), in the local timezone of your operation.

   Example GET Request: (The specific endpoint and any necessary query parameters, like date ranges, should be used as per the Optibus API specification. Example below uses /v2/drivers/absences with date filtering.)

   GET /v2/drivers/absences?fromDate=2024-01-01&toDate=2024-01-31&page=1
   Authorization: <YOUR_API_TOKEN>
   

   Query Parameters:

   • driverIds: Comma-separated list of driver IDs to filter for (optional)
   • absenceCode: Comma-separated list of absence type codes to filter for (optional)
   • fromDate: Returns only absences that end on or after this date (YYYY-MM-DD) (optional)
   • toDate: Returns only absences that start on or before this date (YYYY-MM-DD) (optional)
   • page: 1-indexed page number (defaults to 1)

   Example JSON Response:

   {
     "absences": [
       {
         "absenceId": "uuid-string-for-absence-1",
         "absenceCode": "SICK",
         "driverId": "driver-id-123",
         "startDate": "2024-01-10",
         "endDate": "2024-01-11",
         "startTime": 540,
         "endTime": 1020,
         "note": "Flu symptoms"
       },
       {
         "absenceId": "uuid-string-for-absence-2",
         "absenceCode": "VACATION",
         "driverId": "driver-id-456",
         "startDate": "2024-01-15",
         "endDate": "2024-01-20"
       },
       {
         "absenceId": "uuid-string-for-absence-3",
         "absenceCode": "PERSONAL",
         "driverId": "driver-id-456",
         "startDate": "2024-01-25",
         "endDate": "2024-01-25",
         "startTime": 600,
         "endTime": 840,
         "note": "Appointment"
       }
     ],
     "pagination": {
       "currentPage": 1,
       "totalPages": 3,
       "nextPage": 2
     }
   }
   

3. Process Absences:

   • Check the pagination property in the response to determine if there are more pages to fetch.
   • For each page, iterate through the absences array.
   • For each absence object:
     • Existing Absence: If the absenceId already exists in your external HR system, update the corresponding record with the latest information.
     • New Absence: If the absenceId does not exist in your external HR system, create a new absence record using the data provided.
     • Note: startTime and endTime are optional and represent minutes from midnight. Convert these to time strings if needed (e.g., 540 minutes = 09:00).
   • Continue fetching subsequent pages by incrementing the page parameter until all pages have been processed.

This section gives step-by-step guides for common integration scenarios with external fleet management systems. For help with your particular integration scenario, please contact your Optibus Customer Success Manager.

This use case details how to create and update vehicle information in Optibus when changes are made in your external fleet management system.

Process:

1. Vehicle Creation in External Fleet Management System:

   When a new vehicle is created in your fleet management system, make a POST request to the /v1/vehicles API endpoint.

   Example Request:

   POST /v1/vehicles
   Authorization: <YOUR_API_TOKEN>
   Content-Type: application/json
   
   {
     "vehicles": [
       {
         "id": "vehicle-001",
         "licensePlate": "ABC-123",
         "regionName": "North Region",
         "depotName": "Main Depot",
         "type": "Double Decker",
         "model": "Routemaster"
       }
     ]
   }
   

   Notes:

   • Each request is atomic - either all vehicles are created successfully, or none are created.
   • Maximum 1000 vehicles per request.
   • We recommend using the ID of the vehicle in the external fleet management system as the id field in the request, so that the vehicle has the same identifier in both of your systems.

2. Vehicle Modification in External Fleet Management System:

   When an existing vehicle is edited in your fleet management system, make a PUT request to the /v1/vehicles API endpoint.

   Example Request:

   PUT /v1/vehicles
   Authorization: <YOUR_API_TOKEN>
   Content-Type: application/json
   
   {
     "vehicles": [
       {
         "id": "vehicle-001",
         "licensePlate": "ABC-456",
         "parkingLocation": "Bay 15",
         "type": "Double Decker",
         "model": "Routemaster",
         "decommissioned": false
       }
     ]
   }
   

   Notes:

   • This endpoint expects a full representation of the vehicle - omitting optional fields will clear them.
   • Maximum 1000 vehicles per request.
   • PUT does not support regionName or depotName fields.

This use case describes how to regularly update an external fleet management system with vehicle information from Optibus using a recurring job (e.g., a cron job).

Process:

1. Fetch Vehicles from Optibus:

   Make a GET request to the /v1/vehicles API endpoint. The response is paginated.

   Example Request:

   GET /v1/vehicles?page=1&isDecommissioned=false
   Authorization: <YOUR_API_TOKEN>
   

   Example Response:

   {
     "vehicles": [
       {
         "id": "vehicle-001",
         "licensePlate": "ABC-123",
         "parkingLocation": "Bay 15",
         "mainRegionPeriod": {
           "regionName": "North Region",
           "depotName": "Main Depot"
         },
         "type": "Double Decker",
         "model": "Routemaster",
         "decommissioned": false,
         "customAttributes": {
           "capacity": 42
         }
       }
     ],
     "pagination": {
       "currentPage": 1,
       "totalPages": 5
     }
   }
   

2. Process Vehicles:

   • For each vehicle in the vehicles array, create or update the corresponding record in your fleet management system using the vehicle's id as the identifier.
   • If pagination.currentPage < pagination.totalPages, increment the page parameter and repeat until all pages are processed.

This use case details how to create and update vehicle downtime information in Optibus when changes are made in your external fleet management system.

Process:

1. Downtime Creation or Update in External Fleet Management System:

   When a vehicle downtime is created or updated in your fleet management system, make a PUT request to the /v1/vehicles/downtimes API endpoint.

   Example Request:

   PUT /v1/vehicles/downtimes
   Authorization: <YOUR_API_TOKEN>
   Content-Type: application/json
   
   {
     "downtimes": [
       {
         "downtimeId": "downtime-001",
         "vehicleId": "vehicle-001",
         "startDate": "2024-02-01",
         "endDate": "2024-02-03",
         "note": "Scheduled maintenance"
       }
     ]
   }
   

   Notes:

   • If downtimeId is provided and exists, the downtime will be updated; otherwise, a new downtime is created.
   • If downtimeId is omitted, a new downtime with an auto-generated ID will be created.
   • Each request is atomic - either all downtimes are created/updated successfully, or none are.
   • Maximum 1000 downtimes per request.
   • Note: times are represented as minutes from midnight (e.g., 540 = 09:00, 1020 = 17:00), in the local timezone of your operation.
   • If startTime and endTime are omitted, the downtime covers entire day(s).
   • If endDate is omitted, the downtime is ongoing indefinitely.

This use case describes how to regularly update an external fleet management system with vehicle downtime data from Optibus using a recurring job (e.g., a cron job).

Process:

1. Fetch Vehicle Downtimes from Optibus:

   Make a GET request to the /v1/vehicles/downtimes API endpoint. The response is paginated.

   Example Request:

   GET /v1/vehicles/downtimes?fromDate=2024-01-01&toDate=2024-01-31&page=1
   Authorization: <YOUR_API_TOKEN>
   

   Example Response:

   {
     "downtimes": [
       {
         "downtimeId": "downtime-001",
         "vehicleId": "vehicle-001",
         "startDate": "2024-01-10",
         "endDate": "2024-01-12",
         "startTime": 540,
         "endTime": 1020,
         "note": "Scheduled maintenance"
       },
       {
         "downtimeId": "downtime-002",
         "vehicleId": "vehicle-002",
         "startDate": "2024-01-15",
         "note": "Out of service indefinitely"
       }
     ],
     "pagination": {
       "currentPage": 1,
       "totalPages": 2
     }
   }
   

2. Process Downtimes:

   • For each downtime in the downtimes array, create or update the corresponding record in your fleet management system using the downtimeId as the identifier.
   • Note: times are represented as minutes from midnight (e.g., 540 = 09:00, 1020 = 17:00), in the local timezone of your operation.
   • If pagination.currentPage < pagination.totalPages, increment the page parameter and repeat until all pages are processed.

This section gives step-by-step guides for common query scenarios with Optibus Operations for retrieving operational plan data. For help with your particular query scenario, please contact your Optibus Customer Success Manager.

This section utilizes the /v2/operational-plan endpoint for all operational plan data requests.

This use case details how to fetch a list of duties assigned to specific drivers within a given date range and extract associated block and vehicle information. This is useful for synchronizing driver schedules, auditing assignments, or building custom reports.

Process:

1. Prepare Your Request:

   • Determine the date range (fromDate and toDate parameters) for which you want to retrieve duties.
   • Optionally identify the driverUuids of the drivers whose duties you want to retrieve. These should be provided as a comma-separated string. If omitted, information for all drivers is returned.
   • Optionally, you can specify depotUuids to filter the operational plan by specific depots. This parameter expects one or more depot UUIDs as a comma-separated string. Note: The UUIDs for depots can be obtained from the /v1/regions endpoint, where they correspond to the regionUuid property.
   • Optionally, you can set includeUnassigned=true (in conjunction with driverUuids) to also include unassigned tasks for context around those drivers.

2. Make a GET Request to the Operational Plan Endpoint:

   • Use the /v2/operational-plan API endpoint.
   • Include the fromDate, toDate, and any desired optional parameters (driverUuids, depotUuids, etc.) as query parameters.

Example GET Request:

GET /v2/operational-plan?fromDate=2024-06-01&toDate=2024-06-07&driverUuids=driver-uuid-123&depotUuids=depot-uuid-abc
Authorization: <YOUR_API_TOKEN>

Example JSON Response Snippet (Relevant sections):

The response is an array of depot plans. The following example highlights the properties crucial for linking drivers to duties, blocks, and vehicles, showing how to derive the necessary IDs for your table.

[
  {
    "depotUuid": "depot-uuid-abc",
    "depotName": "Main Depot",
    "assignments": [
      {
        "date": "2024-06-01",
        "driverAssignments": [
          {
            "driver": "driver-uuid-123",
            "assignments": ["task-uuid-A"]
          }
        ],
        "vehicleAssignments": [
          {
            "vehicle": "vehicle-id-XYZ",
            "assignments": ["block-id-1"]
          }
        ],
        "properties": []
      }
    ],
    "blocks": [
      {
        "id": "block-id-1",
        "displayId": "block-display-id-B1",
        "type": "block",
        "disabled": false,
        "summary": { "type": "Standard Bus" },
        "events": [
          {
            "dutyId": "task-uuid-A",
            "eventId": "event-uuid-X"
          }
        ]
      }
    ],
    "tasks": [
      {
        "id": "task-uuid-A",
        "type": "duty",
        "displayId": "Duty 501",
        "summary": {
          "type": "duty",
          "startTime": 480,
          "endTime": 1020
        },
        "events": [
          {
            "uuid": "event-uuid-X",
            "eventType": "deadhead",
            "subType": "depot_pull_out",
            "startTime": "08:00:00",
            "endTime": "08:30:00",
            "blockId": "block-id-1"
          }
        ]
      },
      {
        "id": "task-uuid-SPARE",
        "type": "spare",
        "displayId": "Morning Spare",
        "dutyType": "spare",
        "spareType": "SPARE1",
        "summary": {
          "type": "spare",
          "startTime": 360,
          "endTime": 720
        },
        "events": []
      }
    ],
    "drivers": [
      {
        "id": "driver-ext-123",
        "uuid": "driver-uuid-123",
        "firstName": "John",
        "lastName": "Doe",
        "archived": false
      }
    ],
    "vehicles": [
      {
        "id": "vehicle-id-XYZ",
        "licensePlate": "AB123CD",
        "make": "Mercedes",
        "model": "Citaro"
      }
    ]
  }
]

How to extract duties for a specific driver and build the desired table:

To create a table with columns driverUuid, driverName, dutyId, blockId, vehicleId, follow these steps:

Note on Spare Types: When the spare types feature flag is enabled, spare tasks will include additional properties (spareType, dutyType: "spare") and the displayId will show the configured spare type name instead of the original display ID.

1. Iterate through the Depot Plans and Daily Assignments:

   • The API response is an array of depot plans. Iterate through each depot object.
   • Access the assignments array. For each assignment object (representing a specific date), iterate through its driverAssignments array.

2. Populate Driver and Duty Information:

   • driverUuid: Directly available from driverAssignment.driver.
   • driverName: Look up the driverUuid in the root drivers array (e.g., drivers.find(d => d.uuid === driverAssignment.driver)) to retrieve firstName and lastName.
   • dutyId: The driverAssignment.assignments array contains one or more task IDs assigned to that driver. Each of these is a dutyId.

3. Identify Block(s) and Vehicle(s) for the Duty:

   • For a given dutyId (task ID), find the corresponding object in the root tasks array.
   • Iterate through the events array of that task. An event within the duty will contain a blockId.
   • From Block ID to Vehicle ID:
     • Go back to the assignments object for the current date.
     • Access its vehicleAssignments array.
     • Find the vehicleAssignment object where its assignments array includes your blockId.
     • The vehicle property of that vehicleAssignment object is the vehicleId you need for the table row.

This use case demonstrates how to retrieve duties and a detailed list of all service trips within each duty. This provides a granular view of an operational day.

Process:

1. Prepare Your Request:

   • Specify the desired date range using fromDate and toDate parameters.
   • Optionally, set includeStops=true if you need detailed stop information for each trip. Be aware that enabling this can significantly increase response time and payload size.

2. Make a GET Request to the Operational Plan Endpoint:

   • Use the /v2/operational-plan API endpoint, including the date range query parameters.

Example GET Request:

GET /v2/operational-plan?fromDate=2024-06-15&toDate=2024-06-15&includeStops=true
Authorization: <YOUR_API_TOKEN>

Example JSON Response Snippet (Relevant sections):

The tasks array contains the duty objects. The overall duty start/end times can be found in the summary object (as minutes from midnight). Each duty contains an events array detailing the activities within it.

[
  {
    "assignments": [
      {
        "date": "2024-06-15",
        "driverAssignments": [
          {
            "driver": "driver-uuid-456",
            "assignments": ["task-uuid-B"]
          }
        ]
      }
    ],
    "tasks": [
      {
        "id": "task-uuid-B",
        "type": "duty",
        "displayId": "Duty 700",
        "summary": {
          "type": "duty",
          "startTime": 420,
          "endTime": 960
        },
        "events": [
          {
            "uuid": "event-uuid-E",
            "eventType": "deadhead",
            "subType": "depot_pull_out",
            "startTime": "07:00:00",
            "endTime": "07:30:00"
          },
          {
            "uuid": "event-uuid-F",
            "eventType": "service_trip",
            "startTime": "07:30:00",
            "endTime": "08:15:00",
            "tripId": "service-trip-201",
            "optibusRouteId": "route-R2",
            "direction": 1,
            "stops": [
              { "id": "stop-1", "name": "Main St.", "time": "07:30:00" },
              { "id": "stop-2", "name": "Oak Ave.", "time": "07:45:00" }
            ]
          },
          {
            "uuid": "event-uuid-G",
            "eventType": "service_trip",
            "startTime": "08:30:00",
            "endTime": "09:15:00",
            "tripId": "service-trip-202",
            "optibusRouteId": "route-R2",
            "direction": 2
          }
        ]
      }
    ]
  }
]

How to extract duties with service trips:

1. Identify Duties:

   • Iterate through the top-level tasks array in the API response.
   • A task object with "type": "duty" represents a duty.
   • The date for the duty is found by cross-referencing task.id with the assignments array to find the corresponding date.

2. Extract Service Trips within each Duty:

   • For each identified duty (task object), access its events array.
   • Service Trips: An event where eventType is "service_trip" represents a service trip. You can extract startTime, endTime, tripId, optibusRouteId, direction, and any other relevant details available directly on the event object.
   • Deadhead Events: Events with eventType: "deadhead" represent non-service movements. You can filter these out or process them separately as needed.

This use case explains how to identify duties (tasks) that have been explicitly cancelled for a given day. This is essential for managing daily operations and reporting on changes.

Process:

1. Prepare Your Request:

   • Specify the fromDate and toDate parameters to cover the specific day you are interested in. For a single day, fromDate and toDate will be the same.

2. Make a GET Request to the Operational Plan Endpoint:

   • Use the /v2/operational-plan API endpoint with the desired date range.

Example GET Request:

GET /v2/operational-plan?fromDate=2024-06-10&toDate=2024-06-10
Authorization: <YOUR_API_TOKEN>

Example JSON Response Snippet (Relevant sections):

The assignments array contains a properties sub-array. An entry with disabled: true directly indicates a cancelled task.

[
  {
    "assignments": [
      {
        "date": "2024-06-10",
        "driverAssignments": [],
        "vehicleAssignments": [],
        "properties": [
          {
            "taskId": "task-uuid-cancelled-A",
            "disabled": true,
            "cancellationReason": {
              "reason": "Vehicle Breakdown",
              "reasonCode": "VEHICLE_BREAKDOWN"
            },
            "assignmentType": "driverAssignment"
          },
          {
            "taskId": "task-uuid-active-B",
            "disabled": false,
            "assignmentType": "driverAssignment"
          }
        ]
      }
    ],
    "tasks": [
      {
        "id": "task-uuid-cancelled-A",
        "type": "duty",
        "displayId": "Duty 900 C",
        "summary": { "type": "duty", "startTime": 540, "endTime": 1080 },
        "events": []
      },
      {
        "id": "task-uuid-active-B",
        "type": "duty",
        "displayId": "Duty 700 A",
        "summary": { "type": "duty", "startTime": 420, "endTime": 900 },
        "events": []
      }
    ]
  }
]

How to get a list of duties for a certain day which were cancelled:

1. Fetch Operational Plan: Make a GET request to the /v2/operational-plan endpoint for your desired fromDate and toDate.
2. Access Assignment Properties: Once you receive the response, iterate through the assignments array. For each daily assignment object, navigate to its properties array.
3. Filter for Disabled Tasks: Iterate through each object within the properties array. Check the value of the disabled property: If property.disabled is true, the taskId associated with this property represents a cancelled duty.
4. Retrieve Cancelled Duty (Task) Details:
   • For each taskId identified as disabled: true, you can find the corresponding full duty object in the top-level tasks array (e.g., tasks.find(t => t.id === property.taskId)).
   • Optionally, you can also extract the cancellationReason object from the properties entry for more context.

This guide provides technical instructions for integrating with the Optibus Driver App's "custom notification actions" feature.

Custom actions allow you to configure interactive buttons that appear on specific notifications sent to drivers. When a driver taps a button, it opens a web page that you host. This enables a variety of integrations, such as:

• Displaying a location on a map.
• Linking to an external resource or document.
• Building a form to acknowledge a notification, which can be recorded in a separate IT system.

How It Works

1. A driver receives a notification in the Optibus Driver App containing one or more custom action buttons.
2. The driver taps a button.
3. The app opens the pre-configured URL in a web browser.
4. The Optibus app automatically appends two query parameters to your URL: optibusPayload and optibusSignature.

This feature is configured via the Limit notifications visibility preference in Optibus Operations. To enable and set up the custom action buttons, please contact your Optibus Customer Success Manager for assistance. They will help you configure the button text, target URL, and other parameters to suit your specific use case.

When a driver activates a custom action, your web page will receive a URL containing two critical query parameters. Any query parameters you originally included in the URL will also be preserved.

3.1. Parsing the optibusPayload Parameter

The optibusPayload contains all the contextual information for your web page. To use it, you must first URL-decode the string and then parse it as a JSON object.

JavaScript Example:

// The URL of the page opened by the Driver App.
const url = new URL(window.location.href);

// 1. Get the raw payload string from the URL's search parameters.
const rawPayload = url.searchParams.get("optibusPayload");

// 2. Parse the URL-encoded JSON string.
const payload = JSON.parse(rawPayload);

console.log(payload);

Payload Schema

The parsed payload object will conform to the following schema:

{
  "customAction": {
    "key": "<string>"
  },
  "notification": {
    "id": "<uuid>",
    "driverId": "<string>",
    "type": "<string>",
    "params": {
      // Schema is dependent on the notification 'type'
    }
  },
  "payloadGeneratedAt": "2024-10-11T13:46:56.610Z"
}

Field Descriptions:

• notification.id: The unique UUID of the notification that triggered the action.
• notification.driverId: The ID of the driver who received the notification.
• notification.type: The type of notification (e.g., assignTask). The schema of the params object depends on this value.
• notification.params: An object containing data specific to the notification type. Contact your Customer Success Manager for the exact schema for a given notification type.
• customAction.key: A custom string identifier you specify during the URL configuration.
• payloadGeneratedAt: An ISO 8601 timestamp indicating when the driver tapped the button.

3.2. Verifying the optibusSignature (Recommended)

The optibusSignature parameter allows you to verify that the request was genuinely initiated by the Optibus system and has not been tampered with. Verification is optional but highly recommended for any security-sensitive application.

The signature is created by signing the raw optibusPayload string (before JSON parsing) using the RSA-SHA256 algorithm. You can verify it using a public key provided by Optibus.

Public Key: You can obtain the required public key from the Optibus public key API endpoint.

Signature Verification Example (Node.js)

This example demonstrates how to verify the signature and check the payload's timestamp to prevent replay attacks.

const crypto = require("node:crypto");

// Use the public key fetched from the aforementioned Optibus API endpoint.
const publicKey = "";

// Extract the parameters from the URL.
// In a real application, you would get this from the incoming request.
const url = new URL("https://your-service.com/action?...");
const rawPayload = url.searchParams.get("optibusPayload");
const signature = url.searchParams.get("optibusSignature");

// 1. Verify the signature's authenticity.
const verifier = crypto.createVerify("RSA-SHA256");
verifier.update(rawPayload);
verifier.end();

const isVerified = verifier.verify(publicKey, signature, "base64");
if (!isVerified) {
  throw new Error("Invalid signature. The request is not authentic.");
}

// 2. (Optional but Recommended) Check if the payload is recent to prevent replay attacks.
const maxPayloadAge = 5 * 60 * 1000; // 5 minutes in milliseconds
const parsedPayload = JSON.parse(rawPayload);
const payloadTimestamp = new Date(parsedPayload.payloadGeneratedAt).getTime();

if (Date.now() - payloadTimestamp > maxPayloadAge) {
  throw new Error("Payload is too old. Possible replay attack.");
}

// If verification passes, you can proceed with your logic here.
console.log("Signature and timestamp are valid.");

The following is an example of a complete URL your service might receive after a custom action is triggered.

https://www.optibus.com/?optibusPayload=%7B%22notification%22%3A%7B%22id%22%3A%22b82df1ce-6420-47a6-be06-52b97c9965c5%22%2C%22driverId%22%3A%2233774450%22%2C%22type%22%3A%22assignTask%22%2C%22params%22%3A%7B%22calendarDate%22%3A%222024-10-11%22%2C%22taskName%22%3A%5B%7B%22name%22%3A%224%22%2C%22type%22%3A%22duty%22%2C%22endTime%22%3A1476%2C%22startTime%22%3A920%7D%5D%7D%7D%2C%22customAction%22%3A%7B%22key%22%3A%22OPEN%22%7D%2C%22payloadGeneratedAt%22%3A%222024-10-11T14%3A57%3A49.872Z%22%7D&optibusSignature=arML2T%2B4zu345r1xT78wYbjMZf8VUAmWXylOQUNkGf7isj7KppV75JQURiYufQxwlKmp9qVbk8SMIO3iKHs2FcU0XylBhzpa9QhK4ewyE6SfEhEuZKF7IzkwuL%2B6hJS13Hkqli5IzJKIt0pewVZaBBEREzuqtgm7KQZCCvwoT4nvFnt9kPcSDhJ0jui4IKXfsmBIpdo6XrVgxz72Rgc5ugHlJB9ZmtZ95r%2FBN5ZbBqS%2FThxyaogkLbfcpuFAGuewN2VWFoMVDUU38k0UT3S%2Bb1ZG9bqaeaXRe9tyNJv9JurRCistIAuD%2F4ThgseoLuopb8scJqst8Dp%2FM1XlP0rMYA%3D%3D

API endpoints for managing drivers.

API endpoints for managing absences for drivers - i.e. periods where they are unavailable for work.

API endpoints for managing employment periods for drivers - i.e. periods where they are employed, hired, terminated, etc.

API endpoints for managing custom attributes for drivers - i.e. additional properties that can be set for drivers - including querying and updating their historical values.

API endpoints for managing driver groups.

API endpoints for managing vehicles.