Create a booking via API

Overview

Creating the payload for a custom booking can be somewhat complex without understanding some basic concepts of MotionTools. That’s why we will start this article by giving you a quick intro into these concepts.

If you want an easy way to simply get started, you have the option to simply log into the MotionTools Dashboard, create a booking using the Webbooker and check the Developer Tools of your browser to see a valid sample payload.

• Concepts
• Create a booking: required info
• Sample request payload
• Related resources

Concepts

Create a booking: required info

Now that we’re familiar with the most important concepts, we’re ready to create our first booking.

To do so, at a minimum we need the following pieces of information:

• Stops: this is a simple one → we need a few locations that will represent stops in our booking. Anything would do here, just make sure the stops are located inside your service area.
• instant vs scheduled: decide whether you want the booking to be dispatched immediately, or if needs to be scheduled for later. Bear in mind that whatever you select needs to be allowed by the scheduling configuration associated with the service area the booking will belong to. 

You can’t create instant bookings outside open hours, nor can you schedule bookings to be fulfilled outside open hours. Furthermore, you need to check to see if instant, scheduled, or both are enabled for the would-be service area.

Obtaining the scheduling configuration relevant for a list of locations (i.e. the stops) can be done via our dedicated endpoint built specifically for this purpose.

• Desired capabilities: these are sent as key-value pairs. You can find out all the capabilities currently defined on your account using the capability introspection endpoint.
  • Note: If you plan to use a service other than the default service not all capabilities might be available. You can check your configured services, as well as the capabilities that are enabled for each service, here.
• Customer: when creating bookings as an admin (or using an API Token) a valid customer_id is required. Bookings created by an account that has the Customer role do not need the customer_id specified.

• [Optional] Idempotence Key: An optional idempotence key of your choice, representing for example an order ID on your side when integrating with the API.

  Using an idempotence key will prevent creating two bookings with the same idempotence key in MotionTools, ensuring that edge case conditions like network failures when sending the create API call response or failing to process the successful create on your end lead to duplicated bookings, as our API will complain about duplicate idempotence keys on subsequent re-create attempts.

• 🔐 Authentication: An API Token is required to authenticate our request against the MotionTools backend. The token is provided via an Authorization header. See more information here:
  • MotionTools API Introduction
  • Create an API Token

Besides the above, you can check the API reference for the #CreateHailingBooking endpoint to see the complete list of all supported parameters and options when creating a booking.

Sample request payload

An example payload to create a booking can be seen below. Keep in mind however that it’s unlikely for the payload below to work on your setup, given that creating a booking is highly dependent on the capabilities, services & scheduling configuration specific to your account and your account only.

// Headers
//
// Authentication: Bearer 
// Accept-Language: en-US

// Payload
{
  "booking": {
    "customer_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",
    "requested_capabilities": {
        "vehicle_type": "bike_cargo",
        "assistance": "one_helper"
    },
    "scheduled_at": "now",
    "stops": [
      {
        "city": "Hamburg",
        "country": "Germany",
        "lat": 53.633621999999995,
        "lng": 9.9974128,
        "street": "Hamburg Airport",
        "type": "pickup",
        "zip_code": "22335"
      },
      {
        "city": "Bezirk Altona",
        "country": "Germany",
        "lat": 53.5434024,
        "lng": 9.9404465,
        "street": "MotionTools",
        "type": "dropoff",
        "zip_code": "22767"
      }
    ],
    "version": 2
  }
}

Sample create hailing booking payload

Let’s explore the contents.

"customer_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0"

This is just the customer id for whom the booking is created.

"requested_capabilities": {
      "vehicle_type": "bike_cargo",
      "assistance": "one_helper"
}

As the name suggests, these are the capabilities of the new booking. In your case, the key/values contents of the requested_capabilities object will differ, and will match the capabilities configured for your setup.

"scheduled_at": "now"

This represents the scheduling configuration. now indicates that this is an instant booking, not a scheduled one. If this were a scheduled booking, the contents of the scheduled_at field would have been an ISO8601 formatted timestamp, e.g. 2022-03-20T02:31:00+02:00 or equivalent.

"stops": [
      {
        "city": "Hamburg",
        "country": "Germany",
        "lat": 53.633621999999995,
        "lng": 9.9974128,
        "street": "Hamburg Airport",
        "type": "pickup",
        "zip_code": "22335"
      },
      {
        "city": "Bezirk Altona",
        "country": "Germany",
        "lat": 53.5434024,
        "lng": 9.9404465,
        "street": "Van-der-Smissen-Straße",
        "type": "dropoff",
        "zip_code": "22767"
      }
    ],

The above represents the two stops of the booking. Notable details are the values of the type field in each stop, as well as the lat / lng. The other fields, such as city, country, street, etc are not mandatory to be present. Furthermore, a stop supports more details on creation time, however all said details are optional.

For a complete specification, check the API reference.

"version": 2

This indicates that the second, more recent, version of defining bookings is used. Always needs to be present, and value must always be 2.

Besides the payload itself, don’t forget to also add the necessary headers:

• Authentication
• Accept-Language

That’s it! Congratulations 🙌

You have just created your first MotionTools booking via the API! 🎉

Related resources

• Introduction to hailing bookings
• Hailing booking behaviour
• Hailing booking stops
• Introduction to hailing booking matching features