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 your organization page on the Dispatch App, click ‘Edit Organization Settings’ and enter your callback URL into the field provided.

Request Body Parameters

Parameters Description
unassigned
 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.
en_route_to_pickup
 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.
en_route_to_drop_off
 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.
cancelled
 The order has been cancelled.

JSON Example

Sample Request
{
event: "order.status_change",
data: {
event_id: status.id,
public_url: public_order_url(status.order),
created_at: status.created_at,
previous_status: status.previous_status,
current_status: status.status,
order_id: status.order_id
}
}

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 not passed in 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_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 not passed in 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_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]=ChIJEzCKuyMo9ocRgBUThO3i8UY
&pickup_contact=patrick
&pickup_phone_number=555-555-5555
&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]=ChIJEzCKuyMo9ocRgBUThO3i8UY
&drop_off_notes=something
&drop_off_contact=you
&drop_off_phone_number=555-555-5555
&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]=ChIJEzCKuyMo9ocRgBUThO3i8UY&pickup_contact=patrick&pickup_phone_number=555-555-5555&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]=ChIJEzCKuyMo9ocRgBUThO3i8UY&drop_off_notes=something&drop_off_contact=you&drop_off_phone_number=555-555-5555&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