Create a hailing booking via API

ℹ️  Creating a hailing booking (API Docs) is one of the more complex interactions with our 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

Service area

A service area essentially represents a well-defined zone where your business operates. Besides representing an area on the map, a service area in MotionTools also controls the following:

You can have an unlimited number of service areas: from many service areas each the size of a few blocks, to one single service area that covers the whole globe!

To create a hailing booking, first you need to create a service area via the Dashboard.

Scheduling configuration

Defines the scheduling modes - Instant vs Scheduled, and also configures the “opening hours” of your business. A scheduling configuration is attached to one or more service areas and you can define multiple scheduling configurations.

Like with service areas, scheduling configurations are created via the Dashboard.

Capabilities

Capabilities represent booking properties defined by you, and are specific to your setup.

For instance, if you run an instant delivery business, one capability could be Order Size which would have Small, Medium, Large as possible values. If your business however is an on-demand hailing moving service, you could define 2 capabilities: Car Size - Van / Small Truck / Large Truck & Helpers - 1 Helper/ 2 Helpers.

Capabilities play an important role when matching bookings to drivers. If we take the example above with the Car Size capability - if a booking is created and the Car Size - Large Truck capability is requested, then only drivers that have a Large Truck will be matched with the booking.

Capabilities are defined by you, however you need to talk to your Customer Success Manager to add them in our system. See here.

💡  Further reading: Grouping capabilities into services

Booking stops

Stops represent the fundamental unit of work associated with a booking. Stops have multiple properties, such as contact details, proofs of stop completion, additional information, custom content, and (very important) type (pickup / drop-off), status and location. A booking needs to have at least one stop.

When creating a booking, the service area that a stop belongs to is identified based on the location of the stop. Depending on how your setup is configured, stops need to either be all within a valid service area, only the first one, or just the first & last stop need to be within a service area. See here more about booking validation.

A stop can also be defined by mentioning a Saved place when creating the booking, instead of passing in a lat/ lng pair. For more info, see Hailing booking stops

Payment info

If payments are enabled, the payment method needs to be specified on booking create. Otherwise, if payments are disabled, the payment method can be left empty.

For the sake of simplicity, we won’t work with payment methods when creating a booking in this article, but supported payment methods are mentioned in our API reference - just expand the request body.

 

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:

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 <API Token>
// Accept-Language: en-US

// Payload
{
"booking": {
"customer_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0"
"requested_capabilities": {
"vehicle": "bike",
"bag_size": "large"
},
"scheduled_at": "now",
"stops": [
{
"city": "Bezirk Altona",
"country": "Germany",
"lat": 53.5434024,
"lng": 9.9404465,
"street": "MotionTools",
"type": "dropoff",
"zip_code": "22767"
},
{
"city": "Hamburg",
"country": "Germany",
"lat": 53.633621999999995,
"lng": 9.9974128,
"street": "Hamburg Airport",
"type": "pickup",
"flow": "single_step",
"group": "1",
"zip_code": "22335"
}
],
"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": "bike",
"bag_size": "large"
}

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": "Bezirk Altona",
"country": "Germany",
"lat": 53.5434024,
"lng": 9.9404465,
"street": "MotionTools",
"type": "dropoff",
"zip_code": "22767"
},
{
"city": "Hamburg",
"country": "Germany",
"lat": 53.633621999999995,
"lng": 9.9974128,
"street": "Hamburg Airport",
"type": "pickup",
"flow": "single_step",
"group": "1",
"zip_code": "22335"
},
]

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

Was this article helpful?
0 out of 0 found this helpful

Articles in this section