Step 3: Configure Dispatches

Now that you have set up the infrastructure, you can kick off your operations by working on the dispatches. Dispatches allow you to transport goods to a particular location or multiple locations. They may have stops or tasks in between. As a fleet manager, it is imperative to plan and organize a dispatch effectively, so that it best utilizes the route, the driver HOS, as well sticks to the timelines.

In this step, you will be using the following endpoints:

• 3A: Fetch the dispatch forms
• 3B: List the dispatch locations
• 3C: Create a dispatch
• 3D: Update a dispatch
• 3E: Fetch the latest updates

3A: FETCH THE DISPATCH FORMS

A form is a template that is to be filled by the drivers whenever they arrive or depart from the dispatch location. The forms may include details such as weight, amount, quantity, or even the bill of lading.

FETCH DISPATCH FORMS: GET https://api.gomotive.com/v1/forms

• This endpoint will retrieve all the available forms for your company. You can use these forms for your daily dispatch.

3B: LIST THE DISPATCH LOCATIONS

📘

NOTE

You must first create a dispatch location before you use this endpoint to fetch the dispatch locations. Use the POST https://www.gomotive.com/v1/dispatch_locations You can specify the radius of the area when arriving to or departing from a location. This allows Motive to auto detect the dispatch location.

The dispatch locations are the points if pick-up, drop-off, or even an additional stop. it is important to note that every stop on a dispatch myst have a dispatch location. This can be specified by mentioning a physical address of even a GPS coordinate.

LIST THE DISPATCH LOCATIONS: GET https://api.gomotive.com/v1/dispatch_locations

• The response will fetch a list of all the dispatch locations that you have created. Select the appropriate one for your current operation.

3C: CREATE A DISPATCH

A dispatch is a collection of stops, each with their own set of forms, which can be in either a planned, active, cancelled, or completed state. A driver can have only one active dispatch while having any number of planned dispatches.

A dispatch consists of a minimum of two stops. The first is called the shipper stop (where the dispatch begins) and the last is called the consignee stop (where the dispatch is completed). Any other stops in between are considered additional stops, and are called dispatch stops in our system.

CREATE A DISPATCH: POST https://api.gomotive.com/v1/dispatches

• The POST method for this endpoint only accepts a JSON object in the body of the request. It creates a new dispatch that will be visible to the driver, and that contains the IDs of all involved vehicles, assets, driver, stops, and forms, along with many other details, in addition to up to ten custom fields where you can store additional dispatch information.

3D: UPDATE A DISPATCH

An update to a dispatch can involve either one or more than one PUT calls to the endpoints. It depends on what you are updating in the dispatch. You may be adding a stop, or removing one. Sometimes you may have to change the driver, or even the vehicle, or just have to update the status of the dispatch.

ADD A NEW STOP: PUT https://api.gomotive.com/v1/dispatches

• Modify the JSON object to add a new stop in the dispatch.

REMOVE A STOP: PUT https://api.gomotive.com/v1/dispatches

• Modify the existing JSON to remove the stop.

CHANGE THE DRIVER OR THE VEHICLE: PUT https://api.gomotive.com/v1/dispatches

• A dispatch can be in either a planned, active, cancelled, or completed state. A driver can have only one active dispatch while having any number of planned dispatches. While a dispatch is still in ‘planned’ status, you can change things like the driver and vehicle for it. You cannot make these changes for an ‘active’ status dispatch.

UPDATE THE STATUS OF A DISPATCH: PUT https://api.gomotive.com/v1/dispatches

• A dispatch can be in either a planned, active, cancelled, or completed state. Let’s update a ‘planned’ dispatch to ‘active” status.

3E: FETCH ALL THE UPDATES

After the dispatch you created becomes active, you can hit the /form_entries endpoint for updates on the lifecycle of the dispatch. Recall that a dispatch corresponds to multiple forms, and that forms are templates containing fields for a driver to fill out when arriving or departing from each dispatch location. A form entry, then, occurs when a driver fills out a form at a stop. The form_entries object contains the information that the driver has filled in.

FETCH ALL THE UPDATES: GET https://api.gomotive.com/v1/form_entries

• Optionally provide a list of dispatch IDs, driver IDs, and/or vehicle IDs to filter the form entries. You can also filter the list by specifying a time window for the form entry, using the min_created_at and max_created_at date fields. The response contains details identifying the form, the dispatch, the vehicle, the location, and of course the data that the form required the driver to input.