Step 1: Sync Entities

In this step, you must sync entities such as Users, Vehicles, and Assets between Motive and your current system. This step is important as this will ensure a sync between both the systems. When you are syncing these entities, the most common issue that you will face is that of the nomenclature or naming of the data. You can then correct those issues and ensure both systems reflect the exact data for accurate integration of data between both the systems.

👍

SYNC

Motive supports bidirectional synchronization of all available entities on both platforms (users, vehicles, and assets). Begin your complete TMS integration by synchronizing all the entities.

1A: SYNC USERS

The first thing that you must do is to create a sync between Motive and your system with regards to your users. To do that, you must use the following endpoints:

LIST USERS: GET/https://api.gomotive.com/v1/users

Motive defines the following as users:

📘

NOTE

In this case, we only require the users with the role as "driver".

• Retrieve a list of all the users in Motive by using the above endpoint.
  The response fetches all the drivers associated with the company. You will have details like driver names, driver IDs, Contact Information and others.

UPDATE A USER: PUT/https://api.gomotive.com/v1/users/:id

• After you pull all of the driver details, you must compare the data that exists in Motive and your system. To synchronize the data, ensure all the values for the drivers match accordingly.

📘

NOTE

You must update the external_id for all of the drivers, as this is the field where the internal TMS ID of the driver is stored. This way, any updates you make to our system will include your own internal IDs in addition to those Motive assigns to users.

In your update, provide one or more external_ids for each user by providing with each external_id an associated integration_name, as follows:

"external_ids":[
      {
        "external_id":"201",
        "integration_name":"generic_tms"
      },
      {
        "external_id":"DRV123",
            "integration_name":"generic_maintenance_system"
      }

1B: SYNC VEHICLES

As a next step, you must synchronize all the vehicles between Motive and your system. To do this, you must use the following endpoints:

LIST VEHICLES: GET/https://api.gomotive.com/v1/vehicles

• Retrieve a list of all the vehicles in Motive by using the above endpoint. The response fetches all the vehicles that are available in Motive as well as other details such as make, model, and VIN, license information, fuel type, and the driver with which the vehicle is currently associated with.

UPDATE VEHICLES: PUT/https://api.gomotive.com/v1/vehicles/:id

• After you pull all of the vehicle details, you must compare the data that exists in Motive and your system. To synchronize the data, ensure all the values for the vehicles match accordingly.

📘

NOTE

You must update the external_id for all of the vehicles, as this is the field where the internal TMS ID of the driver is stored. This way, any updates you make to our system will include your own internal IDs in addition to those Motive assigns to vehicles.

In your update, provide one or more external_ids for each vehicle by providing with each external_id an associated integration_name, as follows:

"external_ids":[
      {
        "external_id":"201",
        "integration_name":"generic_tms"
      },
      {
        "external_id":"Truck123",
        "integration_name":"generic_maintenance_system"
      }

1C: SYNC ASSETS

In the next step, you must sync all the assets that are available for the company. Use the following endpoints for fetching the assets as well as updating them:

LIST ASSETS: GET/https://api.gomotive.com/v1/assets

• Retrieve a list of all the assets in Motive by using the above endpoint. The response fetches all the assets that are available in Motive as well as other details such as assets’ types, models, asset gateway information, and current status.

UPDATE AN ASSET: PUT/https://api.gomotive.com/v1/assets/:id

• After you pull all of the asset details, you must compare the data that exists in Motive and your system. To synchronize the data, ensure all the values for the assets match accordingly.

📘

NOTE

You must update the external_id for all of the assets, as this is the field where the internal TMS ID of the driver is stored. This way, any updates you make to our system will include your own internal IDs in addition to those Motive assigns to assets.

In your update, provide one or more external_ids for each asset by providing with each external_id an associated integration_name, as follows:

"external_ids":[
      {
        "external_id":"201",
        "integration_name":"generic_tms"
      },
      {
        "external_id":"Crane123",
        "integration_name":"generic_maintenance_system"
      }

1D: SYNC DISPATCH LOCATIONS

In this step, you must sync the dispatch locations that you have in the Motive platform with the ones you have in your existing system.

A dispatch location represents the location of a pickup, drop-off, or additional stop. This location can be represented using either an address, latitude and longitude, or both. Every stop on a dispatch must have a dispatch location.

For the syncing of the dispatch locations, you can use the following endpoints:

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

• Retrive a list of all the available dispatch locations in Motive. The response includes details such as dispatch location ID, name, address, lat, lon, arrive and depart radius.

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

• Perhaps you have found a recent dispatch location in your system that has not yet been synchronized in the Motive system. The POST call creates a new dispatch location in Motive's system. Provide the dispatch location’s name, address1, city, state, country; optionally provide its zip, lat, lon, arrive_radius, depart_radius, phone.

UPDATE AN EXISTING DISPATCH: PUT /https://api.gomotive.com/v1/dispatch_locations/:id

• If you want to update the information about an existing dispatch location in the Motive system, the PUT call can be used to do that. It takes in similar attributes as the POST call.

DELETE A DISPATCH LOCATION: DEL / https://api.gomotive.com/v1/dispatch_locations/:id

• Now let’s say you have also found a recently invalid dispatch location in your system, which you also want to remove from Motive's system. The DELETE call requires only the dispatch locations’ ID.