Connect Motive: bring fleet vehicle locations into tracking

Complete the Motive OAuth 2.0 flow outside this system, paste the access token into Integration, leave the API base URL on its default unless you use a regional endpoint, test, map and activate — vehicle locations then feed TMS tracking.

The Motive connector reads vehicle locations from your Motive fleet (formerly KeepTruckin) and turns them into tracking events in TMS, so a shipment in transit can be followed by vehicle position. That is its only job: it reads vehicle locations only. It does not pull orders, does not create dispatches or loads, does not read driver logs or hours-of-service records, and does not write anything back to Motive. One connection works with one Motive access token.

Prerequisites#

• A Motive fleet account with vehicles that report locations, and the vehicles you want to follow already set up in Motive.
• A way to complete the Motive OAuth 2.0 authorization_code flow outside this system — authorize at gomotive.com/oauth/authorize and exchange the code at gomotive.com/oauth/token. This connection has no in-system authorize button: you bring a finished access token and paste it in.
• The token must carry the vehicle location permission. Without that permission the test answers MISSING_SCOPE, so check the App permissions in the Motive Developer Portal before you test.
• You know whether your fleet uses the default Motive API address or a regional endpoint. Most fleets use the default and leave base_url empty.

Get your credentials#

1. Start the Motive OAuth 2.0 flow outside this system: open gomotive.com/oauth/authorize and approve access for your fleet App, following the authorization_code flow your Motive App was set up with.
2. Exchange the authorization code at gomotive.com/oauth/token to get the access token. The token is a long string, in the form shown in the fill-in step, starting with characters like eyJraWQiOiIyMDIwXzEi.
3. Copy the full access token at once and keep it ready to paste. Do not shorten it and do not add spaces or line breaks — a trimmed token answers INVALID_TOKEN.
4. Remember that this token expires. When it expires, this connection cannot renew it for you: you run the same OAuth authorization_code flow again and paste the new token. Plan for that renewal before the fleet goes quiet.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Motive → New connection.
2. token — required, OAuth2 access token: paste the full access token you exchanged at gomotive.com/oauth/token, for example a long string starting with eyJraWQiOiIyMDIwXzEi. It is a password-type field and is stored as a secret.
3. base_url — optional, API base URL: leave it empty to use the default https://api.gomotive.com. Fill it only when your fleet uses a regional Motive API endpoint, and then fill that endpoint address exactly as Motive gave it.

Test the connection#

Click Test connection. With a token filled in, the test sends one real, read-only request: GET {base_url}/v2/vehicle_locations with your token as the Bearer credential, with a 12-second timeout. A 200 answer means the token is accepted and the vehicle location endpoint is reachable. A 401 answer comes back as INVALID_TOKEN — the token is invalid or has expired. A 403 answer comes back as MISSING_SCOPE — the token does not carry the vehicle location permission. A request that does not answer in time comes back as TIMEOUT. Fix the cause named by the code, then test again: the test does not change any data in Motive.

Mapping / pick a template#

Pick the Motive standard mapping. It takes each vehicle location returned for your fleet and turns it into a TMS tracking event for that vehicle, so positions line up with the vehicle and shipment you follow in TMS. After the test passes, run one read and compare one vehicle that you know is on the road: check its latest position here against the same vehicle in Motive. If the position matches, the mapping is right and you can activate.

Activate#

After activation, the connection reads vehicle locations from Motive through your token and keeps TMS tracking updated with the latest fleet positions. Watch the first reads in Runs / Logs and compare a few vehicles with Motive before leaving the connection unattended, and diarise the token expiry date so you can renew the token in time.

What this connection does not do: it does not pull orders or loads from Motive, it does not create or change dispatches, it does not read driver logs, hours-of-service or fuel records, and it does not send positions or any other data back to Motive. Keep handling those jobs in Motive itself or in the systems where that work happens.

FAQ#

Test fails with INVALID_TOKEN (401)

Motive refused the token: it is invalid or it has expired. Access tokens from the OAuth authorization_code flow do not last forever, and a token that was trimmed while copying is refused in the same way — the test cannot tell a cut-off token from an expired one.

Run the Motive OAuth authorization_code flow again — authorize at gomotive.com/oauth/authorize and exchange the code at gomotive.com/oauth/token — copy the new access token in full, paste it into the token field, save, and test again. There is no refresh button in this connection: a new token always comes from a new OAuth run.

Test fails with MISSING_SCOPE (403)

The token itself was accepted, but it does not carry the vehicle location permission, so Motive will not let it read vehicle locations. The values you filled in are not the problem: the permission was not granted to the App when the token was issued.

Open the Motive Developer Portal, check the App permissions and make sure vehicle location access is granted, then run the OAuth flow again to issue a token with that permission, paste the new token in, and test again.

Test fails with TIMEOUT

The vehicle location request did not answer within 12 seconds. That is a reachability problem on the way to the Motive API — a wrong base_url, a regional endpoint that does not answer for your fleet, or a temporary Motive API slowdown — not proof that the token is wrong.

Check base_url first: leave it empty for the default https://api.gomotive.com unless your fleet really uses a regional endpoint. Then test again. If the timeout repeats with the default address, wait a short while and retry, and keep the failing time from Runs / Logs when you ask for help.

It connected before, then vehicle positions stopped updating

The most common cause is the access token reaching its expiry date. The connection keeps the old token and cannot renew it on its own, so reads start failing — usually with INVALID_TOKEN in the logs — while nothing else in the connection changed.

Run the OAuth authorization_code flow again, paste the new access token into the token field, save and test. Once the test passes, positions resume. Note the new expiry date this time so the next renewal happens before it lapses.

Connected, but one vehicle shows no position

The connection returns the locations Motive has for the fleet: if Motive itself has no current location for that vehicle — the vehicle is off, out of coverage, or not reporting — there is nothing for this system to show for it. A healthy connection cannot invent a position Motive does not have.

Check that same vehicle in Motive first. If Motive shows a current position and this system does not, run a manual read, compare the vehicle in Runs / Logs, and test the connection again. If Motive shows nothing either, fix the reporting on the Motive side for that vehicle.

Why do no orders or dispatches come in through Motive?

Because this connector only reads vehicle locations. Orders, loads and dispatches are not part of what it can read from Motive, so an empty order list here is expected behaviour, not a broken connection.

Keep creating and managing orders and dispatches in the systems where that work happens, and use this connection for what it does: following the vehicles that carry those shipments in TMS tracking.