Dispatch API Reference

Quickstart Guide

This Dispatch APIs RESTful endpoints that use standard HTTP verbs to send and receive data to and from the Dispatch system. The HTTP verbs that Dispatch supports are listed below

GET HTTP GET - Used to READ data from the Dispatch system.
POST HTTP POST - Used to CREATE data in the Dispatch system

Environments

Dispatch has a testing and demo environment and a production environment. You will need a separate API Key and API Secret for each environment.
Please use the demo environment when testing and developing your applications.

TEST / DEMO ​​https://demo.dispatchit.com/api/external/v1
PRODUCTION ​https://app.dispatchit.com/api/external/v1

Authentication

All calls to the Dispatch API must include an authorization header containing the credentials needed to authenticate with the Dispatch system. Dispatch uses the standard HTTP Authorization header to pass the required credentials to the dispatch system.
HTTP headers are a key / value pair. The HTTP Authorization header format is as follows:
Authorization: Basic


You will use your Dispatch API Key and API Secret to derive the authorization header. Most modern programming languages have libraries that can be used to easily add the Authorization header to any API call. If you need to create the authorization header manually, please note that the “credentials” are derived by base64 encoding the API Key and API Secret, joined by a single colon
(< API Key >:< API Secret >)

Example Authorization Header:
Authorization: Basic amFzb250ZXN0MTIzNCE6dDEYMw==

Other Header Information

The Dispatch API requires the following additional headers to be set.
Accept: */*

Content-Type: application/json

Marketplace

Use the Dispatch Marketplace API to generate an order directly within the Dispatch Marketplace network of drivers from your existing tools or ERP system and track the status from creation to delivery. Streamline your operations, save your business time, and keep your customers happier than ever.
Learn more about the Dispatch Platform

Webhooks

To configure webhooks, go to the Developer Settings page, scroll down to the Webhooks section and click Add / Update Webhooks.

Choose Dispatch Marketplace for the product and enter the URL for Marketplace specific events.

If you have webhooks configured for your organization, Dispatch will automatically send delivery status updates using the schema shown below.

Order Status Event:

Status Description
assigning
 The order has been created and is waiting for a driver to be assigned to it or the order had a driver assigned previously that was unassigned from it.
assigned
 The order has been assigned to a driver and they are on the way to pick it up. Any attempt to cancel an order at or after this point will result in an error.
at_pickup
 The driver has arrived at the pickup location.
out_for_delivery
 The driver has picked up the order and is on the way to the drop-off location.
at_drop_off
 The driver has arrived at the drop-off location.
delivered
 The order has been delivered to the drop-off contact.
canceled
 The order has been canceled.
Sample Event Object
{
event: "order.status_change",
data: {
event_id: 123456,
public_url: "https://example.com",
created_at: "2021-05-11T19:08:01.030Z",
previous_status: "assigning",
current_status: "assigned",
order_id: 12345
}
}

URL Parameters

Dispatch's Marketplace Integration streamlines the processing of getting data from an existing ERP system into Dispatch Marketplace via URL parameters.

URL Parameters are used to easily pre-fill a new order form with information passed in the URL.

In order to utilize this feature, you need to append the query parameters for the fields you want pre-filled on the form in the URL.

Fields marked as *required are required to be passed as a URL parameter.

Fields not passed as URL parameters will be left blank on the order form, and will require the user to manually input that data on the order form prior to saving.

Below is a table of accepted URL parameters.

parameter required type description
delivery_info
reference_number string External Reference or PO number
requester_user_id string External User ID of user that placed the order
vehicle_type * string Type or size of vehicle (possible values: car, midsize, cargo_van, pickup_truck)
quantity_of_packages * number Number of packages/items in order
service_type * string Level of service(possible values: asap, expedited, standard)
needs_unloading_assistance boolean Indicates if order requires assistance unloading.
pickup_date_time_utc string Desired pickup date/time. If null, assumes items are ready for immediate pickup
drop_off_date_time_utc string Desired dropoff date/time. If null, assumes 5pm drop off location
tracking_email_addresses string Email addresses that tracking link will be sent to.
tracking_phone_numbers string Phone numbers that tracking SMS messages will be sent to.
pickup_info
business_name * string Name of pickup business
contact_name * string Name of pickup contact
contact_phone_number * string Phone number of pickup contact; Required format: 123-123-1234
location
address
address_1 * string Pickup Address line 1
address_2 string Pickup Address line 2
city * string Pickup City
state_province_code * string Pickup state or province
postal_code * string Pickup postal code
google_place_id string Pickup Google Place Id
geo_coordinates
lng * string Pickup longitude
lat * string Pickup latitude
pickup_notes string Notes for driver about pickup location
drop_off_info
business_name * string Name of drop off business
contact_name * string Name of drop off contact
contact_phone_number * string Phone number of drop off contact; required format: 123-123-1234
estimated_weight integer Estimated weight in lbs.
location
address
address_1 * string Drop off Address Line 1
address_2 string Drop off Address Line 2
city * string Drop off City
state_province_code * string Drop off State or Province
postal_code * string Drop off Postal code
geo_coordinates
lat * string Drop off latitude
lng * string Drop off longitude
google_place_id string Drop off Google Place Id
drop_off_notes string Drop off notes

Example

Example Query Params
?delivery_info[reference_number]=123456
&delivery_info[requester_user_id]=4256
&delivery_info[vehicle_type]=car
&delivery_info[quantity_of_packages]=1
&delivery_info[service_type]=standard
&delivery_info[needs_unloading_assistance]=false
&delivery_info[tracking_email_addresses]=foo@example.com
&delivery_info[tracking_phone_number]=555-111-2222
&delivery_info[pickup_date_time_utc]=2021-07-30T10:00:00-05:00
&delivery_info[drop_off_date_time_utc=2021-07-30T14:00:00-05:00
&pickup_info[business_name]=Dispatch
&pickup_info[contact_name]=John+Doe
&pickup_info[contact_phone_number]=555-111-2222
&pickup_info[pickup_notes]=Knock+three+times+on+the+front+door
&pickup_info[location][google_place_id]=ChIJYfIJlwIl9ocRN-DfDZYjuLg
&pickup_info[location][geo_coordinates][lat]=44.8331993
&pickup_info[location][geo_coordinates][lng]=-93.2979848
&pickup_info[location][address][address_1]=1401+W+94th+St
&pickup_info[location][address][city]=Bloomington
&pickup_info[location][address][state_province_code]=MN
&pickup_info[location][address][postal_code]=55431
&drop_off_info[business_name]=U.S.+Bank+Stadium
&drop_off_info[contact_name]=John+Doe
&drop_off_info[contact_phone_number]=555-222-3333
&drop_off_info[drop_off_notes]=Watch+out+for+the+guard+dog
&drop_off_info[location][google_place_id]=ChIJ2S4MB2Ets1IRfCsiTN0qtvI
&drop_off_info[location][geo_coordinates][lat]=44.9828807
&drop_off_info[location][geo_coordinates][lng]=-93.2658119
&drop_off_info[location][address][address_1]=401+Chicago+Ave
&drop_off_info[location][address][city]=Minneapolis
&drop_off_info[location][address][state_province_code]=MN
&drop_off_info[location][address][postal_code]=55415
Putting URL together
[base url]/orders/begin?delivery_info[reference_number]=123456&delivery_info[requester_user_id]=4256&delivery_info[vehicle_type]=car&delivery_info[quantity_of_packages]=1&delivery_info[service_type]=standard&delivery_info[needs_unloading_assistance]=false&delivery_info[tracking_email_addresses]=foo@example.com&delivery_info[tracking_phone_number]=555-111-2222&delivery_info[pickup_date_time_utc]=2021-07-30T10:00:00-05:00&delivery_info[drop_off_date_time_utc=2021-07-30T14:00:00-05:00&pickup_info[business_name]=Dispatch&pickup_info[contact_name]=John+Doe&pickup_info[contact_phone_number]=555-111-2222&pickup_info[pickup_notes]=Knock+three+times+on+the+front+door&pickup_info[location][google_place_id]=ChIJYfIJlwIl9ocRN-DfDZYjuLg&pickup_info[location][geo_coordinates][lat]=44.8331993&pickup_info[location][geo_coordinates][lng]=-93.2979848&pickup_info[location][address][address_1]=1401+W+94th+St&pickup_info[location][address][city]=Bloomington&pickup_info[location][address][state_province_code]=MN&pickup_info[location][address][postal_code]=55431&drop_off_info[business_name]=U.S.+Bank+Stadium&drop_off_info[contact_name]=John+Doe&drop_off_info[contact_phone_number]=555-222-3333&drop_off_info[drop_off_notes]=Watch+out+for+the+guard+dog&drop_off_info[location][google_place_id]=ChIJ2S4MB2Ets1IRfCsiTN0qtvI&drop_off_info[location][geo_coordinates][lat]=44.9828807@drop_off_info[location][geo_coordinates][lng]=-93.2658119&drop_off_info[location][address][address_1]=401+Chicago+Ave&drop_off_info[location][address][city]=Minneapolis&drop_off_info[location][address][state_province_code]=MN&drop_off_info[location][address][postal_code]=55415

Testing

The Dispatch “Demo” environment can be used to test integrations before moving to a production environment. Dispatch strongly recommends thorough testing of all API integrations before attempting to place any real live orders. Testing API integrations will reduce the chances of errors that could result in unwanted orders or orders that are missing information critical to completing an order successfully.

Connect

Dispatch Connect is delivery management software that allows you to visualize and organize your daily deliveries— all in one place. Connect the dots between your business, your drivers, your customers, and your bottom line. Use the Dispatch Connect integrations to generate a delivery from your ERP system or other tools and complete the delivery management process while connecting seamlessly with your customers.
Learn more about Dispatch Connect

Auto-Fill Integration via URL Parameters

The Connect Auto-Fill Integration streamlines the process of getting data from an existing ERP system into Dispatch Connect via URL parameters.

URL Parameters are used to easily pre-fill a new delivery form with information passed in the URL.

In order to utilize this feature, you need to append the query parameters for the fields you want pre-filled on the form in the URL.

Fields marked as *required are required for the delivery to be created, but not required to be passed as a URL parameter.

Fields not passed as URL parameters will be left blank on the delivery form, and will require the Connect user to manually input that data on the delivery form prior to saving.

Passing data such as a 'Pickup Location' may overwrite any form defaults selected in Connect Settings. For example, if this toggle is 'on' that means the Organization address will default as the pickup location on each delivery. Implementing URL parameters may push data to that field and would overwrite that preference. The below image shows the toggle that sets form defaults. Ensure you are working with stakeholders to understand these setting preferences.



Below is the table of accepted URL parameters.

Parameters Required Description
job_name
 * The unique job name or reference ID for any given delivery.
delivery_size
 * The amount of units the delivery contains. Used to measure how full a vehicle is.
pickup_address[street]
 * Street address for the delivery pickup location.
pickup_address[city]
 * City for the delivery pickup location.
pickup_address[state]
 * State for the delivery pickup location.
pickup_address[postal_code]
 * Postal code for the delivery pickup location.
pickup_address[google_place_id]
Google place id may be passed if you have it and want to ensure a specific google address is used.

Note: If Google place id is passed it will take precedence over the rest of the address parameters, otherwise the address input will automatically use the first google place result.
pickup_contact
 * Name of the contact at the pickup location responsible for delivery management.
pickup_phone_number
 * Phone number for the pickup contact to enable easy communication if there are issues at vehicle loading or pickup.
pickup_duration_in_minutes
 Service Duration in minutes for the pickup.
pickup_notes
 Notes pertaining to the pickup location to enable the driver to have an easy pickup and loading experience.
drop_off_address[street]
 * Street address for the delivery drop-off location.
drop_off_address[city]
 * City for the delivery drop-off location.
drop_off_address[state]
 * State for the delivery drop-off location.
drop_off_address[postal_code]
 * Postal code for the delivery drop-off location.
drop_off_address[google_place_id]
Google place id may be passed if you have it and want to ensure a specific google address is used.

Note: If Google place id is passed it will take precedence over the rest of the address parameters, otherwise the address input will automatically use the first google place result.
drop_off_contact
 * Name of the contact at the drop-off location that is expecting the delivery.
drop_off_phone_number
 * Phone number for the drop-off contact to enable easy communication if there are issues at drop-off.
drop_off_duration_in_minutes
 Service Duration in minutes for the drop-off.
drop_off_notes
 Notes pertaining to the drop-off location to enabled the driver to have an easy drop-off experience.
email_contacts
 Comma separated list of email addresses that will receive notifications for the delivery as the status updates.
sms_contacts
 Comma separated list of phone numbers that will receive notifications for the delivery as the status updates.
pickup_window_start_at
 *
The earliest time the delivery can be picked up, formatted as datetime ISO 8601.
Note: This will be rounded to the nearest half hour increment.
pickup_window_end_at
 *
The latest time the delivery can be picked up, formatted as datetime ISO 8601.
Note: This will be rounded to the nearest half hour increment.
drop_off_window_start_at
 *
The earliest time the delivery should be dropped off by, formatted as datetime ISO 8601.
Note: This will be rounded to the nearest half hour increment.
drop_off_window_end_at
 *
The latest time the delivery should be dropped off by, formatted as datetime ISO 8601.
Note: This will be rounded to the nearest half hour increment.

Example

Example Query Params
?job_name=something
&delivery_size=2
&pickup_address[street]=3985+Eagan+Outlets+Pkwy+Suite+500
&pickup_address[city]=Eagan
&pickup_address[state]=MN
&pickup_address[postal_code]=55122
&pickup_address[google_place_id]=ChIJDarrczIu9ocR8xqI5UMILkE
&pickup_contact=patrick
&pickup_phone_number=555-555-5555
&pickup_duration_in_minutes=15
&pickup_notes=something
&drop_off_address[street]=6415+Labeaux+Ave+NE
&drop_off_address[city]=Albertville
&drop_off_address[state]=MN
&drop_off_address[postal_code]=55301
&drop_off_address[google_place_id]=ChIJd3jXf3xns1IRxPI3vAxMJ88
&drop_off_notes=something
&drop_off_contact=you
&drop_off_phone_number=555-555-5555
&drop_off_duration_in_minutes=15
&email_contacts=user@example.com
&sms_contacts=321-321-2222%2C321-321-4444
&pickup_window_start_at=2021-01-22T13:00:00-06:00
&pickup_window_end_at=2021-01-22T13:30:00-06:00
&drop_off_window_start_at=2021-01-22T17:00:00-06:00
&drop_off_window_end_at=2021-01-22T17:30:00-06:00
Putting url together
[base url]/connect/deliveries/new?job_name=something&delivery_size=2&pickup_address[street]=3985+Eagan+Outlets+Pkwy+Suite+500&pickup_address[city]=Eagan&pickup_address[state]=MN&pickup_address[postal_code]=55122&pickup_address[google_place_id]=ChIJDarrczIu9ocR8xqI5UMILkE&pickup_contact=patrick&pickup_phone_number=555-555-5555&pickup_duration_in_minutes=15&pickup_notes=something&drop_off_address[street]=6415+Labeaux+Ave+NE&drop_off_address[city]=Albertville&drop_off_address[state]=MN&drop_off_address[postal_code]=55301&drop_off_address[google_place_id]=ChIJd3jXf3xns1IRxPI3vAxMJ88&drop_off_notes=something&drop_off_contact=you&drop_off_phone_number=555-555-5555&drop_off_duration_in_minutes=15&email_contacts=user@example.com&sms_contacts=321-321-2222%2C321-321-4444&&pickup_window_start_at=2021-01-22T13:00:00-06:00&pickup_window_end_at=2021-01-22T13:30:00-06:00&drop_off_window_start_at=2021-01-22T17:00:00-06:00&drop_off_window_end_at=2021-01-22T17:30:00-06:00