v3.0

GoRoute API Documentation

GoRoute is AttriX's routing and delivery management system that integrates your TMS with Geotab devices. Send routes to drivers, receive real-time status updates, exchange messages, and collect proof of delivery data.

🚚 What is GoRoute?

GoRoute connects your Transportation Management System (TMS) with drivers in the field via Geotab devices. Routes published to GoRoute appear on drivers' devices, and all status changes, completed activities, and messages flow back to your system in real-time.

Key Capabilities

Authentication

GoRoute uses Geotab credentials for authentication. All API calls include database and user identification.

🔐 Security Note

All communication must occur over HTTPS. Your TMS endpoints (in Push Mode) must be publicly accessible and secured with valid SSL certificates.

Common Parameters

Parameter Description Example
database Your Geotab database name acme_transport
geotabUserId The Geotab user ID for a specific driver b4CE1BF8

Integration Modes

GoRoute supports two integration approaches. Choose based on your infrastructure and requirements.

🔄 Poll Mode

Simpler Setup

Your TMS polls AttriX endpoints at regular intervals to fetch updates and push route changes.

Advantages

  • ✅ No public endpoints required
  • ✅ Works behind firewalls
  • ✅ Simpler to implement
  • ✅ You control update frequency

You Will Use

  • POST /api/go-route/poll/route/{database}/{driver}
  • GET /api/go-route/poll/route-changes/{database}/{fromDate}
  • GET /api/go-route/poll/messages/{database}/{fromDate}
  • POST /api/go-route/message/{database}/{driver}

⚡ Push Mode

Real-time

AttriX pushes updates to your TMS endpoints in real-time via webhooks.

Advantages

  • ✅ Instant updates
  • ✅ Lower latency
  • ✅ Event-driven architecture
  • ✅ No polling overhead

You Will Implement

  • GET {your-base}/waypoints
  • POST {your-base}/waypoints/{id}
  • POST {your-base}/activities/{id}
  • POST {your-base}/message

Waypoint

A destination to visit along a route. Waypoints are presented in order to drivers.

Lifecycle: Not Started → OTW (On The Way) → IN (Arrived) → OUT (Departed)

Properties

Property Type Required Description
id string Yes Unique identifier for this waypoint. Numbers are accepted but treated as strings.
name string Yes Waypoint description shown to the driver (usually customer name or location)
address string Yes Address for this waypoint. If lat/lon omitted, must be accurate for geocoding.
vehicleName string No The name of the vehicle planned for this route
lat string No Latitude coordinate. Preferred but not required if address is accurate.
lon string No Longitude coordinate. Preferred but not required if address is accurate.
activities Activity[] No List of activities to perform once on site. Can be empty.
trailer1Name string No Assigned trailer name for the trip
trailer2Name string No Assigned 2nd trailer name if applicable
phoneNumber string No Contact phone number at this waypoint
notBefore string No Earliest arrival time (ISO8601 Zulu/UTC)
notBeforeLocal string No Earliest arrival time (ISO8601 local timezone)
notAfter string No Latest arrival time (ISO8601 Zulu/UTC)
notAfterLocal string No Latest arrival time (ISO8601 local timezone)
note string No Additional information for the driver
noteHtml string No HTML-formatted notes (no JS, avoid fancy CSS)
ref string No Internal reference for this trip
po string No Purchase order number
pb string No Pro bill number
shipper string No Shipper for this trip
consignee string No Consignee for this trip
seal1 string No Seal number on 1st trailer
seal2 string No Seal number on 2nd trailer
autoStatusRadius string No Override km radius for auto status (0.5 = 500m)
bumpable boolean No Allow bump requests for this waypoint
navigateOnExit boolean No Auto-open routing app on waypoint OUT
copilotProfile string No CoPilot routing profile to use
lateStatus string No Late status: normal, late_carrier, late_consignee, late_shipper, late_weather_traffic
startTime string No OTW event time (ISO8601 Zulu), null if not started
arrivalTime string No IN event time (ISO8601 Zulu), null if not arrived
departureTime string No OUT event time (ISO8601 Zulu), null if not departed
driverActivities string[] No List of activity actions the driver can publish for this waypoint

Activity

An action or task to complete at a waypoint. Activities are completed after arrival (IN) and before departure (OUT).

Statuses: DONE CANCELLED
Suggested Actions: pickup drop switch stop pin-trailer drop-trailer dispatch customs

Properties

Property Type Required Description
id string Yes Unique identifier for this activity. Numbers are accepted but treated as strings.
action string Yes Action type: pickup, drop, switch, stop, pin-trailer, drop-trailer, dispatch, customs
info string No Description of what is expected (trailer name for pin/drop, commodity for pickup/drop)
label string No Custom label for this activity (defaults to translated action)
outfields Outfield[] No List of outfields to fill when completing. Can be empty.
note string No Extra notes for the driver
noteHtml string No HTML-formatted notes (no JS, avoid fancy CSS)
infoHtml string No HTML-formatted info display
signatureRequired boolean No If true, signature required to complete. Default false.
signatureMode string No How the signature is delivered back. "base64" (default): GoRoute posts the raw PNG data-URI in the signature field. "signed_url": GoRoute generates a signed PDF via its PDF microservice and posts a short-lived GCS URL in signature_url instead.
signatureHtml string No HTML content for signature screen summary
signatureDocuments object[] No BETA BETA (in spec, subject to change). Only used when signatureMode is "signed_url". One entry per POD document to produce, each { id, html, externalRef }: id identifies the document within the activity and is echoed back, html is the body printed on that document (same restricted HTML as signatureHtml), externalRef is the name the finished PDF should be filed under. A stop covering several orders handed over together is signed once and produces one PDF per entry. Omit the field for the ordinary single-document case. When supplied, every document must be produced or the driver is blocked — no partial filing.
signature string No Base64 PNG data-URI posted back when signatureMode is "base64" (null if not completed or if signatureMode is "signed_url")
completionTime string No Completion timestamp (ISO8601 Zulu), null if not completed
allowCompletionOverride boolean No Allow driver to edit completion time. Default false.
inspectionRequired string No Force inspection before completion: "truck" or "trailer"

Outfield

A data field to collect from the driver when completing an activity.

Available Types: text email integer float boolean selection time datetime date image document

Properties

Property Type Required Description
name string Yes Unique identifier for this outfield within the activity
label string Yes Field label shown to the driver
type string Yes Field data type (see types list above)
required boolean Yes If true, driver cannot complete activity without filling this field. Never mark boolean fields as required.
value string No Value as previously posted by GoRoute, or null if not filled
choices string[] No Required for selection type. List of possible values.
documentType string No For document type: POD, BOL, or fuel-receipt
lookForStrings string[] No For document type: strings to look for in scanned document
group string No Group name for applying min/max validation across fields
groupMin integer No Minimum fields in group that must have values
groupMax integer No Maximum fields in group that can have values
requiredIf string No Name of boolean outfield that makes this field required when checked
visibleIf string No Name of boolean outfield that makes this field visible when checked
hideFromSig boolean No If true, this outfield's name and value will not be shown on the activity's signature screen. Default is false when omitted — all outfields are shown on the signature screen by default.
documentIds string[] No BETA BETA (in spec, subject to change). Only applies when the activity carries signatureDocuments. Scopes this answer to particular documents: list the id of each document it belongs on and it is printed on those PDFs only. Omitted means it is printed on every document of the activity. The field stays visible on the signature screen either way — the same person signs for all of them.

Driver Activity Template

Defines an action type that drivers can proactively publish themselves.

Properties

Property Type Required Description
action string Yes Internal identifier for this activity type. TMS must accept published activities of this type.
description string Yes Brief name or description shown to the driver
durationRequired boolean Yes If true, driver must submit duration in minutes
photoRequired boolean Yes If true, driver must upload a picture
infoRequired boolean Yes If true, driver must supply textual information
signatureRequired boolean Yes If true, driver must submit a signature
midTrip boolean Yes If true, can be published between waypoints (waypointId will be null)
outfields Outfield[] No List of outfields to fill when completing. Can be empty.

AttriX Endpoints

These endpoints are hosted by AttriX. Your TMS calls these to interact with GoRoute.

POST https://goroute.attrix.ca/api/go-route/notify/{database}/{driver}

Notify Route Changed

Notify AttriX of a route change for a driver. Routes will be resynched if needed. Used in Push Mode only.

URL Parameters

Parameter Type Required Description
database string Yes The Geotab database name Example: acme_transport
driver string Yes The Geotab user ID for this driver Example: b4CE1BF8

Query Parameters

Parameter Type Required Description
force boolean No Force a hard refresh (default: false) Example: true

Response Example

"ok"
POST https://goroute.attrix.ca/api/go-route/message/{database}/{driver}

Send Message to Driver

Send a message from the TMS to a driver using GoRoute. Can be used in both Poll Mode and Push Mode implementations.

✅ Works in Both Modes

This endpoint can be used in both Poll Mode and Push Mode implementations.

URL Parameters

Parameter Type Required Description
database string Yes The Geotab database name Example: acme_transport
driver string Yes The Geotab user ID, or "all" for broadcast Example: b4CE1BF8

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
message string Yes The message text to deliver Example: Please call dispatch when you arrive
language string No Language code (en/fr). Auto-detected if omitted Example: en
files[] file[] No File attachments (max 10MB each)

Response Example

"ok"

Poll Mode Endpoints

Use these endpoints if you chose Poll Mode integration. Your TMS calls these at regular intervals.

GET https://goroute.attrix.ca/api/go-route/poll/route-changes/{database}/{fromDate}

Get Route Changes

Fetch updates to waypoints since the last sync. Returns an object where keys are driver IDs and values are arrays of changed waypoints.

URL Parameters

Parameter Type Required Description
database string Yes The customer database name Example: acme_transport
fromDate string Yes Last sync timestamp (ISO8601 Zulu) Example: 2024-01-15T01:23:45Z
Response Header: X-Date-Time: The server timestamp to use as fromDate in next request

Response

Returns Waypoint[] . See data model for field details.

POST https://goroute.attrix.ca/api/go-route/poll/route/{database}/{driver}

Post Route

Send an updated route to AttriX for a driver. Replaces /notify and /waypoints endpoints for poll implementations.

URL Parameters

Parameter Type Required Description
database string Yes The customer database name Example: acme_transport
driver string Yes The Geotab user ID Example: b4CE1BF8

Body Parameters

Content-Type: application/json

Parameter Type Required Description
waypoints Waypoint[] Yes Array of waypoints for this driver
GET https://goroute.attrix.ca/api/go-route/poll/messages/{database}/{fromDate}

Get Messages

Get messages received from drivers since the last sync.

URL Parameters

Parameter Type Required Description
database string Yes The customer database name Example: acme_transport
fromDate string Yes Last sync timestamp (ISO8601 Zulu) Example: 2024-01-15T01:23:45Z
Response Header: X-Date-Time: The server timestamp to use as fromDate in next request
POST https://goroute.attrix.ca/api/go-route/poll/templates/{database}

Post Driver Activity Templates

Send updated driver activity templates. Replaces all previous templates for this database.

URL Parameters

Parameter Type Required Description
database string Yes The customer database name Example: acme_transport

Body Parameters

Content-Type: application/json

Parameter Type Required Description
(array) DriverActivityTemplate[] Yes Array of driver activity templates
POST https://goroute.attrix.ca/api/go-route/poll/files/{database}

Upload File

Upload a file to attach to a waypoint. Returns a file ID to use in post-route.

URL Parameters

Parameter Type Required Description
database string Yes The customer database name Example: acme_transport

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
file file Yes The file to upload
GET https://goroute.attrix.ca/api/go-route/poll/get-work-summary/{database}/{geotabUserId}

Get Work Summary

Get a summary of work done in the last 7 days for a driver.

URL Parameters

Parameter Type Required Description
database string Yes The customer database name Example: acme_transport
geotabUserId string Yes The Geotab user ID Example: b4CE1BF8

Push Mode - Your Endpoints

If you chose Push Mode, you must implement these endpoints. GoRoute will call them to deliver updates. The base URL is configured in your AttriX account (e.g., https://api.yourcompany.com/goroute).

⚠️ Important

Your endpoints must be publicly accessible via HTTPS with valid SSL certificates. The paths shown below are appended to your configured base URL.

GET {your-base-url}/waypoints

Get Waypoints

Main endpoint by which GoRoute fetches an up-to-date route for a driver. Order matters - waypoints are presented in array order.

💡 Implementation Note

You implement this endpoint. GoRoute calls it when drivers need route updates.

Query Parameters

Parameter Type Required Description
geotabUserId string Yes The Geotab user ID for this driver Example: b4CE1BF8
database string Yes The Geotab database name Example: acme_transport
force boolean No Hard reload flag from notify or user action Example: true
manual boolean No Driver manually triggered refresh Example: false

Response

Returns Waypoint[] . See data model for field details.

POST {your-base-url}/waypoints/{id}

Update Waypoint

Receive waypoint status updates. Expect OTW, IN, OUT in order. Update start_time (OTW), arrival_time (IN), departure_time (OUT).

💡 Implementation Note

You implement this endpoint. GoRoute calls it when waypoint status changes.

URL Parameters

Parameter Type Required Description
id integer Yes The waypoint ID from GET /waypoints Example: 5

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
geotabUserId string Yes The Geotab user ID Example: b4CE1BF8
database string Yes The Geotab database name Example: acme_transport
status string Yes New status: OTW, IN, OUT, or LATE Example: IN
eventTime string Yes Event timestamp (ISO8601 Zulu) Example: 2024-01-15T14:30:00.000Z
eventTimeLocal string Yes Event timestamp (ISO8601 local) Example: 2024-01-15T09:30:00.000-05:00
distance number No Distance from waypoint in km Example: 14.4
geotabDeviceId string No Current vehicle device ID Example: b38A
odometer number No Vehicle odometer in km Example: 26568.7
lat number No Current latitude Example: 45.5518227
lon number No Current longitude Example: -73.219017
lateStatus string No Late reason (if status=LATE) Example: late_weather_traffic
eta string No ETA to next waypoint (if status=OTW) Example: 2024-01-15T15:00:00.000Z
POST {your-base-url}/activities/{id}

Update Activity

Receive activity completion updates. Sent after waypoint IN and before OUT. Return 422 with field errors to reject.

💡 Implementation Note

You implement this endpoint. GoRoute calls it when activities are completed.

URL Parameters

Parameter Type Required Description
id integer Yes The activity ID from GET /waypoints Example: 8

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
geotabUserId string Yes The Geotab user ID Example: b4CE1BF8
database string Yes The Geotab database name Example: acme_transport
waypointId integer Yes Parent waypoint ID Example: 5
status string Yes Status: DONE or CANCELLED Example: DONE
eventTime string Yes Event timestamp (ISO8601 Zulu) Example: 2024-01-15T14:35:00.000Z
eventTimeLocal string Yes Event timestamp (ISO8601 local) Example: 2024-01-15T09:35:00.000-05:00
signature string No Base64 PNG data-URI of the drawn signature. Present only when signatureMode is "base64" (the default). Example: data:image/png;base64,...
signature_url string No Short-lived GCS signed URL pointing to the generated PDF (~24 h). Present only when signatureMode is "signed_url". Store or forward promptly — the receiver can scan a QR code to retrieve their copy. When the activity carried several signatureDocuments this is the first document's URL, so a TMS that files one POD per activity needs no further handling. Example: https://storage.googleapis.com/goroute-pods/...
signature_documents object[] No BETA BETA (in spec, subject to change). Sent only when the activity carried signatureDocuments. One entry per produced document — { id, ref, url } where id is the identifier you supplied, ref is the externalRef to file that PDF under, and url is its short-lived link. Posted as form fields signature_documents[0][id], signature_documents[0][ref], signature_documents[0][url], signature_documents[1][id], and so on. All of them came from one signature. Example: [{"id":"POD-1","ref":"PO-88421","url":"https://storage.googleapis.com/..."}]
outfields object No Collected field values as name:value pairs Example: {"odometer": 1213}
odometer number No Vehicle odometer in km Example: 26570.2
lat number No Current latitude Example: 45.5518227
lon number No Current longitude Example: -73.219017
cancelReason string No Reason if CANCELLED Example: closed
cancelReasonNotes string No Additional cancel notes Example: Location was closed early
POST {your-base-url}/activities

Publish Activity

Receive driver-initiated activities. Sent after waypoint IN and before OUT (or mid-trip if midTrip=true).

💡 Implementation Note

You implement this endpoint. GoRoute calls it when drivers add unplanned activities.

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
geotabUserId string Yes The Geotab user ID Example: b4CE1BF8
database string Yes The Geotab database name Example: acme_transport
waypointId integer No Parent waypoint ID (null if midTrip) Example: 5
activity_id string Yes GoRoute-generated activity ID Example: 5-d-1
action string Yes Activity type from templates Example: wait-time
info string No Driver-supplied info
duration number No Not sent as a body parameter. A template declaring durationRequired makes GoRoute collect the duration as an outfield named "duration" (integer, minutes), so it arrives inside outfields. photoRequired likewise becomes a "photo" outfield, posted to receive-document.
nextWaypointId string No The next waypoint the driver is heading to. Sent so a mid-trip activity (waypointId null) can still be placed in the day, between the previous stop and that one. Example: 6
start_time string No Start timestamp (ISO8601 Zulu). Sent when the activity was started before being completed. Example: 2024-01-15T14:00:00.000Z
completion_time string Yes Completion timestamp (ISO8601 Zulu) Example: 2024-01-15T14:45:00.000Z
signature string No Base64 signature if required
outfields object No Collected field values
GET {your-base-url}/driver-activity-templates

Get Driver Activity Templates

Return the list of possible driver-initiated activities for this customer.

💡 Implementation Note

You implement this endpoint. GoRoute calls it to get available activity types.

Query Parameters

Parameter Type Required Description
database string Yes The Geotab database name Example: acme_transport

Response

Returns DriverActivityTemplate[] . See data model for field details.

POST {your-base-url}/document

Receive Document

Receive files for image outfields. Sent before activity DONE event. Document outfields with advanced scanning are sent as URLs in update-activity instead.

💡 Implementation Note

You implement this endpoint. GoRoute calls it when drivers upload images.

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
geotabUserId string Yes The Geotab user ID Example: b4CE1BF8
database string Yes The Geotab database name Example: acme_transport
activityId integer Yes The activity ID Example: 8
waypointId integer Yes The waypoint ID Example: 5
outfield string Yes The outfield name requesting the image Example: pod
files[] file[] Yes Image file(s) uploaded
POST {your-base-url}/message

Receive Message

Receive messages sent from drivers using GoRoute.

💡 Implementation Note

You implement this endpoint. GoRoute calls it when drivers send messages.

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
driver string Yes The Geotab user ID Example: b4CE1BF8
database string Yes The Geotab database name Example: acme_transport
message string Yes The message text Example: Running 30 minutes late
POST {your-base-url}/bump-request

Bump Request

Receive a request to bump a waypoint in priority order. If accepted, send a notify.

💡 Implementation Note

You implement this endpoint. GoRoute calls it when drivers request to reorder stops.

Body Parameters

Content-Type: multipart/form-data

Parameter Type Required Description
geotabUserId string Yes The Geotab user ID Example: b4CE1BF8
database string Yes The Geotab database name Example: acme_transport
waypointId integer Yes The waypoint ID to bump Example: 7
GET {your-base-url}/shipment-logs

Get Shipment Logs

Return currently loaded shipment document numbers. Feature flag enabled. Return 503 if unknown.

💡 Implementation Note

Optional endpoint. Only implement if shipment log tracking is enabled.

Query Parameters

Parameter Type Required Description
database string Yes The Geotab database name Example: acme_transport
geotabUserId string Yes The Geotab user ID Example: b4CE1BF8