Reporting on Bookings

This guide provides an overview of how to retrieve booking data from Mobiledock using the bookings export REST API. This endpoint allows you to export bookings based on specific criteria and a pre-configured data structure.

Requirements

To integrate with Mobiledock bookings using the REST API, the following requirements must be met:

Your organisation must have API access.
You have created an API token with the BookingObservation permission.
You have a working Mobiledock configuration that includes bookings.

REST Endpoint

The root endpoint of the Bookings Export API is /api/v2/bookings.

This should be appended to the base URL, specific to the environment that you are working with.

The Bookings Export Endpoint

The primary operation for retrieving booking data is the bookings export endpoint. This endpoint is designed for exporting large datasets in a structured format, using a layout ID to determine the output columns.

Anatomy of a Bookings Export Request

The endpoint is a POST request to /api/v2/bookings.

Query Parameters

The following query parameters control pagination:

skip: The number of records to skip from the beginning of the result set.
count: The maximum number of records to return.

Note: The maximum number of bookings allowed to be queried at once is 1000, a limit enforced by the API.

Request Body

The request body is a JSON object that defines the export configuration.

Property	Description
`layoutId`	An ID that specifies the layout configured in the Mobiledock UI. This layout determines the columns and their order in the exported data.
`filter`	An object that allows you to apply specific criteria to the booking query.
`format`	The output format of the data. Supported values are `json` or `csv`.
`viewAs`	The type of data to return. Supported values are `bookings` or `tasks`.

The Filter Property

The filter property is the most complex and powerful parameter when querying bookings. All filter properties are optional and can be used simultaneously in any combination, allowing you to refine the search for bookings that match specific criteria.

Breakdown of Filter Inputs

Below is a brief overview of the available filter inputs, what they mean, and their input type. More details of each input type can be found in the following sections.

Filter Input	Description	Input Type
`activeTime`	Filter bookings by their active time, which is the time period between their scheduled start and scheduled end time.	`Comparison`
`area`	Filter bookings by specific areas, either by name or ID.	`EntityRefComparisonInput`
`bookingOption`	Filter bookings by their booking options, using either its name or ID.	`EntityRefComparisonInput`
`carrier`	Filter bookings by the carrier’s name or ID.	`EntityRefComparisonInput`
`createdTime`	Filter bookings by the creation datetime.	`Comparison`
`document`	Filter bookings that use specific documents by name or ID.	`EntityRefComparisonInput`
`direction`	Filter bookings by direction.	`Comparison`
`documentStatus`	Filter bookings by the document status.	`EntityRefComparisonInput`
`documentType`	Filter bookings by the document type.	`EntityRefComparisonInput`
`fieldValue`	Filter bookings based on custom fields using the `FieldValueFilterInput` object.	`[FieldValueFilterInput!]`
`group`	Filter bookings by groups associated with the booking.	`EntityRefComparisonInput`
`loadQuantity`	Filter bookings by the quantity of specific loads using the `LoadQuantityFilterInput`.	`[LoadQuantityFilterInput!]`
`loadTag`	Filter bookings based on load tags.	`Comparison`
`location`	Filter by the booking location’s name or ID.	`EntityRefComparisonInput`
`modifiedTime`	Filter bookings by the last modified datetime.	`Comparison`
`occupant`	Filter bookings by the occupant’s name or ID.	`EntityRefComparisonInput`
`offsite`	Filter bookings by the offsite’s name or ID.	`EntityRefComparisonInput`
`participant`	Filter bookings by participants involved, either by name or ID.	`EntityRefComparisonInput`
`space`	Filter bookings based on the space they are assigned to, using name or ID.	`EntityRefComparisonInput`
`status`	Filter bookings by the booking status, using name or ID.	`EntityRefComparisonInput`
`vehicle`	Filter bookings by the vehicle’s name or ID.	`EntityRefComparisonInput`

Example Request Payload

{
  "layoutId": "00000000-0000-0000-0000-000000000000",
  "filter": {
    "location": {
      "name": {
        "eq": "Example DC"
      }
    }
  },
  "format": "json",
  "viewAs": "bookings"
}

Understanding the Response Payload

The response from the endpoint is a JSON object containing a data array. Each object within this array represents a single booking.

The keys in each booking object are the column names as defined in the layout. The values are the corresponding data for that booking.

Example Response Payload

{
  "data": [
    {
      "ID": "MDB-25-BBPD-959B",
      "PIN": "44918",
      "POs": "PO-0010, PO-0020, PO-0030",
      "Receivers": "Example DC",
      "Senders": "SUPPLIER A, SUPPLIER B",
      "Pallets": 100,
      "Cartons": 1000,
      "Status": "Completed",
      "Scheduled": "15/05/2025 16:00:00",
      "Carrier": "Example Carrier",
      "Direction": "Inbound",
      "Space": "Bay 03",
    }
  ]
}

Requirements​

REST Endpoint​

The Bookings Export Endpoint​

Anatomy of a Bookings Export Request​

Query Parameters​

Request Body​

The Filter Property​

Breakdown of Filter Inputs​

Example Request Payload​

Understanding the Response Payload​

Example Response Payload​