Skip to main content
All CollectionsDeveloper ResourcesWorking with the API
Bulk create Bookings via Postman with a CSV file
Bulk create Bookings via Postman with a CSV file
Support avatar
Written by Support
Updated today

This article explains how to bulk create a Bookings via Postman with a CSV file.

Overview

Have the following prerequisites been met?

  • You have at least a free account on Postman.

  • You have created an Admin API Key on your MotionTools account.


Step 1: Prepare the CSV file

Duplicate this Google Sheet template and fill in all your bookings' data you want to bulk create.

Booking Information

service_id

  • The Service, which includes possible Capability options. If you don’t fill this out, we’ll take the default service

  • You can find the service_id by opening the Settings page of your tenant, clicking on the Booking services section, and the Service you need the ID from. Then, go to the search bar of your browser and copy the string of numbers at the end of the URL - this is the service ID.

requested_capabilities

  • The requested capabilities for a booking, e.g. the vehicle type

  • Please list each Capability key (e.g. "vehicle_type") and the selected option (e.g. "bike_cargo") for the bookings you create. With our example the format should look like this: “vehicle_type”:”bike_cargo”

  • Make sure to separate each capability with a comma: “vehicle_type”:”bike_cargo”, "delivery_driver": "yes"

  • If you want to find out which capability keys and values you have enabled, you can do so via the API. Read Show capability and List capability values in our API docs.

customer_id

  • The Customer you attach to the booking

  • This can be a placeholder (same for all bookings) if you mention recipient data on each stop instead

  • You can find the customer ID by opening the Customer tab and copying the ID from the list. If you don't see the IDs in the list, open the Edit columns setting and check the checkbox for ID.

scheduled_at

  • Start time of the booking

  • Make sure to use a time for bookings in the future (e.g. 2025-09-26T15:00:00Z) or use now for instant bookings, otherwise booking creation will fail

additional_information

  • Here, you can enter additional information/booking instructions e.g. something like: Please enter through the back door

The stops lat & lng should also be inside a Service area.

managing_organizations

  • The Organization that is handling the booking

  • Enter the ID of an Organization like this: {"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"}

  • You can find the organization ID by opening the Organizations tab of your tenant and clicking on the organization you need the ID from to open the organizations' details page. Then, go to the search bar of your browser and copy the string of numbers at the end of the URL - this is the organization ID.

The following explanations apply to the pickup and drop-off information you need to enter in the sheet. If a column is about the pickup it will have a prefix of pickup_ in the column name (e.g. pickup_location_name), if it's about the drop-off a prefix of dropoff_ (e.g. dropoff_location_name)

Location information

This is the information you need to enter about your pickup and drop-off location.

location_name

Name of the location (e.g. Hub Hamburg) location name from google maps, primär für fahrer sichtbar aber kann man sich ausdenken im prinzip

lat

Latitude of the location (e.g. 53.566805)

lng

Longitude of the location (e.g. 9.898777)

street

Street name of the location (e.g. Main Street)

house_number

House number of the location (e.g. 245)

zip_code

Zip code of the location (e.g. 20537)

city

City of the location (e.g. Hamburg)

country

Country of the location (e.g. Germany)

additional_address_line

For buildings, apartments, etc. (e.g. Building B2)

additional_information

Additional Information about the location (e.g. Please leave the package at the reception)

Contact details

This is the information you need to enter about the contact person at the pickup and drop-off location.

first_name

First name of the contact person (e.g. Jane)

last_name

Last name of the contact person (e.g. Doe)

phone_number

Phone number of the contact person (e.g. 4915783366556)

email

Email address of the contact person (e.g. [email protected])

Stop information

expected_arrival_at

Time of the expected arrival at the stop (e.g. 2025-08-23T15:00:00Z)

expected_departure_at

Time of the expected depature from the stop (e.g. 2025-08-23T16:00:00Z)

custom_content

Custom stops data like checklists visible in the MotionTools app. Learn more in our API Docs

metadata

Custom stops or bookings data visible on the Dashboard only and via API. Learn more in our API Docs


Step 2: Prepare Postman

In the next step, open the Postman application and import the CSV file to create bookings in MotionTools.

Import this example Environment and replace the following credentials:

Import one of the following Collections (depending on your booking structure):

2-stop bookings

1-stop bookings

Bulkcreatebookings_Launch_runner.png


Step 3: Run it in Postman

  • Make sure you select the Environment.

  • Click on Runner on the bottom right.

  • Hit Select File and open your CSV file.

  • The number of iterations are reflected as the columns of your CSV file. It will create a booking for each of them.

  • Drag the Collection into the Runner, then hit Run iterate CSV file to bulk create bookings.

Bulkcreatebookings_Runner_Postman.gif

If it gives you a 200 response, the booking creation was a success and you should find the bookings in your MotionTools dashboard!

If you need to add additional data to the payload you can find the full scope in our API Docs.

Did this answer your question?