Optibus Operations API (2.3.21)

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 third-party HR systems. For help with your particular integration scenario, please contact your Optibus Customer Success Manager.

This use case details how to reflect changes made to driver absences in a third-party HR system within Optibus.

Process:

1. Absence Creation in Third-Party 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.

   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": "08:00:00",
       "endDate": "2024-02-01",
       "endTime": "12:00: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 Third-Party 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.

   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": "08:00:00",
       "endDate": "2024-02-02",
       "endTime": "17:00: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).

3. Absence Deletion in Third-Party 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 a third-party 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 /v1/absences API endpoint.
   • The API response will be an object where each property key is a driverId. The value of each property is an array of absence objects pertaining to that driver.

   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 assumes /v1/absences and date filtering.)

   GET /v1/absences?startDate=2024-01-01&endDate=2024-01-31
   Authorization: <YOUR_API_TOKEN>
   

   Example JSON Response (structured by driver ID):

   {
     "driver-id-123": [
       {
         "absenceId": "uuid-string-for-absence-1",
         "driverId": "driver-id-123",
         "code": "SICK",
         "startDate": "2024-01-10",
         "startTime": "09:00:00",
         "endDate": "2024-01-11",
         "endTime": "17:00:00",
         "notes": "Flu symptoms"
       }
     ],
     "driver-id-456": [
       {
         "absenceId": "uuid-string-for-absence-2",
         "driverId": "driver-id-456",
         "code": "VAC",
         "startDate": "2024-01-15",
         "startTime": "00:00:00",
         "endDate": "2024-01-20",
         "endTime": "23:59:59",
         "notes": "Annual leave"
       },
       {
         "absenceId": "uuid-string-for-absence-3",
         "driverId": "driver-id-456",
         "code": "PERSONAL",
         "startDate": "2024-01-25",
         "startTime": "10:00:00",
         "endDate": "2024-01-25",
         "endTime": "14:00:00",
         "notes": "Appointment"
       }
     ],
     "driver-id-789": []
   }
   

3. Process Absences:

   • Iterate through the primary object returned by the API. Each key in this object is a driverId.
   • For each driverId, retrieve the array of associated absence objects.
   • Iterate through this array of absences. For each absence object:
     • Existing Absence: If the absenceId from the absence object already exists in your third-party HR system, update the corresponding record with the latest startDate, startTime, endDate, endTime, and any other relevant fields.
     • New Absence: If the absenceId does not exist in your third-party HR system, create a new absence record in your system using the data provided in the absence object.

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

A roster describes the daily operator runs grouped into packages of (repeating) weekly work assignments.