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

If you have webhooks configured for your organization, Dispatch will automatically send order status updates using the schema shown below. 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.

Orders generally move through the statuses in the order listed below, ending at delivered. However, there are times when this is not the case, i.e. a driver accepts an order, and then changes their mind. In this case, an order have changed from assigned to assigning, and then back to assigned when a new driver accepted the order. In each case, both the current, and the previous status are listed in the JSON request body.

Dispatch will re-try calling your webhook endpoint up to 5 times. After each failure, we will wait an increasing amount of time before trying again until the endpoint is reached, or we have received 5 failures.

Verifying Requests

The X-Dispatch-Signature and X-Dispatch-Timestamp headers may be used to verify the authenticity of webhook requests originating from Dispatch. The X-Dispatch-Signature header contains an HMAC using the SHA256 hash function, and the X-Dispatch-Timestamp header contains a timestamp in the form of the number of seconds since the Unix Epoch.

When configuring a Dispatch Marketplace webhook, Dispatch generates a random key which is used to compute the HMAC. The key is accessible on the Developer Settings page in the Webhooks section.

To verify the authenticity of the request, you will use the timestamp header information and the body of the request to compute the HMAC, and compare it to the HMAC in the signature header. Identical values indicated the request is authentic.

Compute the signature with the following steps:

Step 1

Extract the header information.

Step 2

Extract the raw contents of the body of the request. It is important to not process the body with a JSON parser for this step.

Step 3

Combine the contents of the request body with the X-Dispatch-Timestamp header, separated by the character .

Step 4

Compute the HMAC using the SHA256 hash function, your webhook key from the Developer Settings page, and the concatenated string from the previous step.

Step 5

Compare the computed hash with the contents from the X-Dispatch-Signature header. Secondarily, to prevent replay attacks, you can compute the difference between the current time and the timestamp you received from Dispatch. It is up to you to decide what your tolerance is for the difference between the times.

Examples

The statuses are listed below with a brief description of what each one means, along with an example of the JSON request body.

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.

JSON Example

Sample Request  |  assigning
{
event: "order.status_change",
data: {
event_id: 987654,
public_url: "https://example.com/order/fa02aa718992f6f9",
created_at: "2021-10-25 03:34:19 UTC",
previous_status: "",
current_status: "assigning",
order_id: 12345
}
}

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.

JSON Example

Sample Request  |  assigned
{
event: "order.status_change",
data: {
event_id: 987654,
public_url: "https://example.com/order/fa02aa718992f6f9",
created_at: "2021-10-25 03:54:19 UTC",
previous_status: "assigning",
current_status: "assigned",
order_id: 12345
}
}

at_pickup

The driver has arrived at the pickup location.

JSON Example

Sample Request  |  at_pickup
{
event: "order.status_change",
data: {
event_id: 987654,
public_url: "https://example.com/order/fa02aa718992f6f9",
created_at: "2021-10-25 04:13:19 UTC",
previous_status: "assigned",
current_status: "at_pickup",
order_id: 12345
}
}

out_for_delivery

The driver has picked up the order and is on the way to the drop-off location.

JSON Example

Sample Request  |  out_for_delivery
{
event: "order.status_change",
data: {
event_id: 987654,
public_url: "https://example.com/order/fa02aa718992f6f9",
created_at: "2021-10-25 04:19:19 UTC",
previous_status: "at_pickup",
current_status: "out_for_delivery",
order_id: 12345
}
}

at_drop_off

The driver has arrived at the drop-off location.

JSON Example

Sample Request  |  at_drop_off
{
event: "order.status_change",
data: {
event_id: 987654,
public_url: "https://example.com/order/fa02aa718992f6f9",
created_at: "2021-10-25 07:09:19 UTC",
previous_status: "out_for_delivery",
current_status: "at_drop_off",
order_id: 12345
}
}

delivered

The order has been delivered to the drop-off contact.

JSON Example

Sample Request  |  delivered
{
event: "order.status_change",
data: {
event_id: 987654,
public_url: "https://example.com/order/fa02aa718992f6f9",
created_at: "2021-10-25 07:10:19 UTC",
previous_status: "at_drop_off",
current_status: "delivered",
order_id: 12345,
delivery_photos: ["http://s3.amazonaws.com/example.com/proof_of_delivery_photo.jpg"],
delivery_signee_name: "Ryan Andrews"
}
}

canceled

The order has been canceled.

JSON Example

Sample Request  |  canceled
{
event: "order.status_change",
data: {
event_id: 987654,
public_url: "https://example.com/order/fa02aa718992f6f9",
created_at: "2021-10-25 03:42:19 UTC",
previous_status: "assigning",
current_status: "canceled",
order_id: 12345,
cancellation_reason: "Duplicate order"
}
}

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-10-26T10:00:00-05:00
&delivery_info[drop_off_date_time_utc=2021-10-26T14: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-10-26T10:00:00-05:00&delivery_info[drop_off_date_time_utc=2021-10-26T14: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


Webhooks

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

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

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

Delivery Status Event:

Status Description
preparing
 A route is associated with a vehicle and in the process of being built, optimized, and validated on the Dashboard.
sent_to_driver
 Route has been sent to the driver for pickup.
en_route
 Driver is currently completing stops on the route for today.
complete
 All stops on the route have been completed, canceled, or marked as incomplete.
canceled
 The delivery has been canceled.
Sample Event Object
{
event: "delivery.status_change",
data: {
event_id: 123456,
public_url: "https://example.com",
created_at: "2021-05-11T19:08:01.030Z",
previous_status: "sent_to_driver",
current_status: "en_route",
delivery_id: 12345
}
}