Connect Motive for telemetry and trip evidence

Prerequisite: platform provisioning

Motive is provisioned in two layers. Conterminal enables the provider for your workspace; you own the actual credential material. Until the first layer is done, nothing on the screen works. Open the account menu and select Integrations, or go directly to Carrier Integrations. The Motive card carries four status badges:

Platform Enabled / Platform Disabled

Whether Conterminal has provisioned the Motive provider for your workspace. This is the gate everything else sits behind.

API Key Ready / API Key Missing

Whether a Motive API key is stored. This is the credential that drives the roster poll, timecards, geofences, and receipt generation.

Photos Enabled / Telemetry Only

Whether a Motive web session token is stored. Photos on a trip receipt come from that session, not from the API key.

Web Login Ready / Web Login Missing

Whether both a Motive web user email and a web password are stored. Both are required — one without the other still reads Web Login Missing.

Underneath the badges, Current mode summarizes the same state in one line: Provisioning disabled, Credentials required, Telemetry-only trip receipts, or Trip receipts with photos.

If provisioning has not happened, an amber banner says: “Platform provisioning has not enabled Motive for this tenant yet. Ask a platform admin to enable Carrier Integrations from the company detail page or the carrier provisioning workspace.” That is a request to Conterminal, not something you can action yourself.

Saving credentials

The Tenant Credentials block has eight fields. Everything is stored encrypted and nothing is ever displayed back to you — a field holding a saved value shows the placeholder Stored value preserved unless replaced. The rule printed above the fields is the one to remember: Leave a field blank to keep the currently stored value.

1. Paste the Motive API Key. This is the only field that is genuinely required. It authenticates every Motive API call Conterminal makes — roster, hours, driving periods, geofences, and trips.
2. Add the web login if you want photos. Fill Web User Email and Web Password with a Motive web account Conterminal may sign in as. Both are needed before Refresh Photo Session becomes usable.
3. Or paste a session token directly. Web Session Token takes a Motive X-Web-User-Auth token, and Web Session Expires At takes an ISO timestamp in the shape 2026-04-10T18:00:00Z. This is the manual alternative to letting Conterminal log in for you.
4. Select Save Credentials. On success the screen shows “Motive credentials updated.”, the badges re-evaluate, and every field is cleared. The cleared fields do not mean the values were lost — they mean the form has no reason to hold secrets any longer.

Testing

Test Credentials makes a single live request to Motive for one driver record. It is fast, safe to repeat, and writes nothing. Read the sentence it returns carefully, because each one describes a different level of readiness:

“API key is valid. A Motive web session token is already stored for photo retrieval.”

Fully configured. Receipts can include breadcrumb photos.

“API key is valid. Motive web login credentials are stored. Use Refresh Photo Session to bootstrap or renew photo access.”

The key works and Conterminal can log in for you, but no session token exists yet. Run the refresh.

“API key is valid. No Motive web session or web-login material is stored, so receipts will generate without photos.”

Telemetry-only. Everything except photos works: roster, hours, timecards, geofences, receipts.

“No Motive API key is configured for this tenant.”

Nothing is stored yet. Paste the key and save before testing again.

Refreshing the photo session

Motive's breadcrumb photos are not exposed through the API key. They are read with a web session token — the same credential a person holds after signing in to Motive in a browser. Rather than making you extract that token by hand, Conterminal drives a headless browser sign-in against Motive's login page with the stored web email and password, and keeps the resulting token.

1. Confirm Web Login Ready. Refresh Photo Session is disabled unless the provider is enabled and both a web user email and a web password are stored. A disabled button here is nearly always a missing password, not a broken integration.
2. Select Refresh Photo Session. The button reads Refreshing while the sign-in runs. This is a real browser session against Motive, so it takes noticeably longer than the credential test.
3. Answer the verification prompt if it appears. If Motive asks for multi-factor verification, a dialog headed Complete Motive Verification opens with the field One-Time Verification Code. Paste the current authenticator or SMS code and select Verify And Continue.
4. Read the result. Success reports “Motive web session refreshed successfully.” and the Photos Enabled badge lights up.

If Motive rejects the login outright you get its own visible error text, or “Motive rejected the supplied web login credentials.” if nothing readable was shown. A wrong or expired code returns “Motive did not accept the one-time code. Try the current code again.” and leaves the dialog open so you can enter the next code without restarting.

Linking terminals to geofences

The Friendly Terminal Geofence Linking block ties Conterminal's terminals to the geofences you already maintain in Motive. Receipt correlation uses those links to replace terminal dwell that would otherwise have to be inferred from split Motive trips.

1. Save an API key first. Without one, an amber banner reads “Save a Motive API key above before loading geofences for terminal linking.” and Load Motive Geofences stays disabled.
2. Select Load Motive Geofences. Conterminal pages through your Motive geofences and reports how many it found, for example “Loaded 42 Motive geofences.” An empty account returns “No Motive geofences were returned for this tenant.”
3. Pick a Friendly Terminal. The dropdown lists Conterminal's canonical terminals. Underneath, the screen shows which underlying terminal backs it, its address, and how many terminal rows roll up into it.
4. Pick a Motive Geofence and save. The geofence dropdown stays disabled until you have loaded the list — it reads Load Motive geofences first until then. The button reads Save Link for a new mapping and Replace Link when the terminal is already mapped. Success confirms “Friendly terminal geofence mapping saved.”

You map each terminal family once, not each row. In Conterminal's own words: “Child terminal rows such as 88 OOCL roll up to the same friendly terminal, so you only need to map each terminal family once.” Everything already mapped appears under Current Friendly Terminal Links with its geofence name and ID, and a Clear Link button that reports “Friendly terminal geofence mapping cleared.”

The driver-link queue

Telemetry only reaches a driver record once that driver is linked to a Motive ID. The Motive Driver Linking panel is where you do the linking. It is fed by the 15-minute poll, which scores each unlinked Motive roster driver against your Conterminal drivers on email, phone, and name.

Each row shows the Motive display name, a confidence chip, the Motive ID, and whatever email, phone, and status Motive returned. Confidence is a plain threshold on that score:

high

An exact email match on its own clears the bar, as does a name match backed by a matching phone number or by several shared name tokens. These are the rows Accept All acts on.

medium

Real but partial evidence — an exact name match with nothing corroborating it, or a matching phone number alone. Read the row before accepting.

low

Only fragments overlap, typically one shared name token. Treat the suggestion as a hint, not an answer.

none

Nothing matched at all, so no driver is suggested. Pick one yourself, create a new driver, or dismiss the row.

1. Accept a suggested match. When the poll found a candidate, the row reads Suggested: followed by the Conterminal driver name. Select Accept to link them.
2. Choose your own. With no suggestion, the row shows a Choose a driver dropdown listing your active, not-yet-linked drivers. Pick one, then Accept.
3. Create the driver. If the Motive driver has no Conterminal counterpart, select Create New. The inline form takes Driver Name — prefilled from Motive — and Employment Type, then Create Driver creates the driver and links it in one step.
4. Dismiss what does not belong. Dismiss hides a row for good; the poll will not re-surface it.
5. Clear the easy ones in bulk. Accept All High-Confidence carries a count in its label and links every high-confidence row that still has a valid target. It reports back, for example, “Linked 7 drivers (2 skipped).”

An empty queue is normal and says so: “No unlinked Motive drivers — the roster poll will surface new ones here.” Every accepted link is written to the driver's change history, so the driver record shows when and by whom it was linked.

Stale Motive Links

A second panel appears only when there is something to report. It lists drivers whose linked Motive ID has dropped off the live roster — deactivated or removed in Motive — with a Needs Recheck chip and the date it went stale. Conterminal never auto-unlinks. Re-check the driver in Motive, and unlink from the driver page if the link is genuinely dead.

Telemetry-only vs photos

Trip evidence works at two levels, and it is worth being clear about which one you are running before you promise a customer photos.

Telemetry-only

Needs the API key alone. The Trip Evidence PDF publishes the matched Motive trip and its timing. This is the default and it is not a degraded mode — it is the evidence most disputes actually turn on.

With photos

Needs a working web session on top of the API key, and needs the matched trip to carry a vehicle. Breadcrumb photos captured around the trip's phase anchors are embedded in the PDF.

Receipts are generated from the trip evidence panel on the job, not from this screen — see cartage and custom jobs for that workflow. Photo outcome is recorded per receipt, and a receipt generated with none is explicitly marked as published without photos rather than being silently downgraded.

Receiving Motive webhooks

The receiver lives at a per-workspace address of the form /api/webhooks/motive/v2/<key>. That key is an unguessable token that identifies your workspace; it is never derived from your organization ID, and support will give you the finished URL to paste into Motive. Every delivery is signed with HMAC-SHA1 over the raw body in the X-KT-Webhook-Signature header, and Conterminal verifies that signature before storing anything.

Once it is live, three event types matter:

Duty status updates

Written straight to the linked driver's last duty status, ahead of the next poll cycle.

Vehicle location updates

Written to the driver's last known coordinates, address, and vehicle, with the sync timestamp.

User created or updated

Never creates or relinks a driver. A new Motive roster driver reaches you through the driver-link queue on the next poll, where you decide.

Events for a Motive driver you have not linked are kept in raw form but change nothing, so a webhook that appears to do nothing usually means the driver-link queue still has work in it. Redeliveries are deduplicated, and Motive retries a delivery Conterminal could not store, so a brief outage does not lose events.

Troubleshooting