Querying Bookings

This guide covers how to retrieve booking data from Mobiledock using both the GraphQL and REST APIs.

Before proceeding, follow the Integration Setup guide.

Overview

In Mobiledock, a booking represents a scheduled visit to a Mobiledock-controlled site. Each booking contains one or more tasks — individual line items describing what is being delivered or collected, including direction, sender, receiver, document reference, and load quantities.

Which API to use

API	Best for
GraphQL (bookings / bookingsV2)	Flexible queries — select exactly the fields you need, filter by many criteria
REST (POST /api/v2/bookings)	Structured exports using pre-configured layouts, CSV or JSON output

Requirements

• 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

GraphQL: Querying bookings

All GraphQL requests are POST requests to /api/v1/graphql.

The bookingsV2 query

The primary operation for retrieving bookings is bookingsV2. It accepts the following arguments:

Argument	Type	Default	Description
filter	BookingsFilterInputV2	null	Filter criteria
start	Int	0	Pagination offset
count	Int	50	Number of results (max 1000)
ordering	BookingOrdering	Time	Sort field: Time, Created, or Modified
ascending	Boolean	true	Sort direction

Example query

GraphQL

query GetBookings {
  bookingsV2(
    count: 500
    start: 0
    filter: {
      location: { id: { eq: "990090c9-7506-487b-9872-c4e65557ae75" } }
      area: { name: { in: ["West Docks", "South Docks"] } }
    }
  ) {
    results
    bookings {
      id
      bookingType
      createdAt
      modifiedAt
      requestedTime
      bookedTime
      duration
      carrier { name }
      space { name }
      area { name }
      location { name }
      vehicle { name size }
      status { name }
      tasks {
        id
        direction
        document { id type { name } }
        senderCore { name }
        receiver { name }
        loads { load { name } quantity loadTag }
      }
    }
  }
}

curl

curl -X POST https://my.mobiledock.com/api/v1/graphql \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetBookings { bookingsV2(count: 500, start: 0, filter: { location: { id: { eq: \"990090c9-7506-487b-9872-c4e65557ae75\" } } }) { results bookings { id status { name } requestedTime carrier { name } } } }"
  }'

JavaScript

const query = `
  query GetBookings($locationId: String!) {
    bookingsV2(
      count: 500
      filter: { location: { id: { eq: $locationId } } }
    ) {
      results
      bookings {
        id
        status { name }
        requestedTime
        carrier { name }
        tasks {
          id
          direction
          loads { load { name } quantity }
        }
      }
    }
  }
`;

const response = await fetch('https://my.mobiledock.com/api/v1/graphql', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query,
    variables: { locationId: '990090c9-7506-487b-9872-c4e65557ae75' },
  }),
});

const { data } = await response.json();
console.log(`Found ${data.bookingsV2.results} bookings`);

Filtering

The filter property is the most powerful parameter. All filter properties are optional and can be combined freely.

Filter	Description	Type
activeTime	Filter by scheduled start/end window	Comparison
area	Filter by area name or ID	EntityRefComparisonInput
bookingOption	Filter by booking option	EntityRefComparisonInput
carrier	Filter by carrier name or ID	EntityRefComparisonInput
createdTime	Filter by creation datetime	Comparison
document	Filter by document name or ID	EntityRefComparisonInput
direction	Filter by direction	Comparison
documentStatus	Filter by document status	EntityRefComparisonInput
documentType	Filter by document type	EntityRefComparisonInput
fieldValue	Filter by custom field values	[FieldValueFilterInput!]
group	Filter by booking groups	EntityRefComparisonInput
loadQuantity	Filter by load quantities	[LoadQuantityFilterInput!]
loadTag	Filter by load tags	Comparison
location	Filter by location name or ID	EntityRefComparisonInput
modifiedTime	Filter by last modified datetime	Comparison
occupant	Filter by occupant name or ID	EntityRefComparisonInput
offsite	Filter by offsite name or ID	EntityRefComparisonInput
participant	Filter by participant name or ID	EntityRefComparisonInput
space	Filter by space name or ID	EntityRefComparisonInput
status	Filter by status name or ID	EntityRefComparisonInput
vehicle	Filter by vehicle name or ID	EntityRefComparisonInput

Tip

When possible, filter by ID rather than name for more reliable results — names can change, and multiple entities may share the same name.

Comparison operators

The Comparison object supports:

Operator	Description
eq	Equal to
neq	Not equal to
gt	Greater than
gte	Greater than or equal
lt	Less than
lte	Less than or equal
in	Included in a list
nin	Not included in a list
match	Contains pattern (like operator)

REST: Bookings export

For exporting large datasets in a structured format using pre-configured layouts, use the REST bookings export endpoint. See the REST Bookings Export reference for the full endpoint specification, parameters, and examples.

Next steps

• API Reference: Bookings — all GraphQL operations for bookings
• REST Bookings Export — full REST endpoint reference
• Error Handling — handle API errors gracefully

If you have further questions, contact assistance@mobiledock.com.