The coding takes days. Deciding which system owns a field when the two disagree is what actually stalls the project.
Key takeaways
Connecting a TMS to another system by API takes four things: credentials and an authentication method, an agreed direction and trigger for the data, a field-by-field mapping with a stable identifier on both sides, and error handling for the day one side is unavailable. The technical work is usually a few days. The mapping and the error handling are where projects fail.
The single most common cause of a stalled integration is not the API. It is that nobody decided which system owns a record when the two disagree.
Vendor documentation tends to describe these clearly if you read past the marketing. Geotab’s developer documentation, for instance, sets out the choice explicitly, framing the decision around the work the customer needs to perform, and distinguishes bounded current-state queries using Get from maintaining a checkpointed stream of changes using GetFeed.
A common and avoidable mistake is polling a request/response endpoint every minute to simulate a feed. It is slower, more fragile and far more likely to hit a rate limit than the mechanism the vendor built for exactly this purpose.
Modern platforms use OAuth 2.0 or issued API tokens; Samsara’s developer documentation lists OAuth 2.0, third-party integration tokens and legacy API tokens as its options. The mechanism matters less than the governance around it.
Two rules earn their keep. First, the integration gets its own service identity, never a named employee’s login — otherwise the integration dies the week that person leaves. Second, permissions are scoped to what the integration actually needs. Geotab’s documentation makes the point directly: API results reflect the authenticated user’s access, so you should test with the integration’s real security model, not only with an administrator account. An integration built and tested as an administrator will fail on the day it is deployed under a restricted account.
Every serious platform limits how fast you may call it, and the limits are published. Samsara documents global ceilings of 150 API requests per second per access token and 200 API requests per second per organization, notes that some endpoints carry more restrictive limits, and states that exceeding a limit returns a 429 Too Many Requests response with a Retry-After header giving the suggested wait in seconds, which the caller should use to back off.
Design to that from the start: batch where the API supports it, respect the retry header rather than looping immediately, and never let a nightly reconciliation job hammer a live endpoint at the same moment dispatch needs it. Those figures are Samsara’s published limits for its own API — check the equivalent page for whichever platform you are integrating with, because they differ.
Reading data is reversible. Writing is not. Geotab’s documentation is blunt about this: API writes change the selected database immediately, and advises developers to develop with test entities, protect tools from selecting the wrong database, and reconcile uncertain outcomes before retrying a write.
That last clause is the one to internalise. If a write times out you do not know whether it succeeded. Retrying blindly creates a duplicate load, a duplicate driver, or a duplicate invoice. The fix is an idempotency strategy — carry your own reference on every record you create, and check before you retry. Samsara’s documentation includes external IDs for exactly this purpose: a stable identifier from your system attached to the record in theirs.
Assume a week of work here regardless of how good both APIs are. The recurring questions:
An integration moves regulated records around, and the obligations travel with them.
Retention and format. The Income Tax Act requires records be kept at the person’s place of business or residence in Canada or another place designated by the Minister, retained for six years from the end of the last taxation year to which they relate, and where kept electronically, retained in an electronically readable format. If an integration is the only path by which data reaches your books, its failure is a records failure.
Duty-status records. The hours-of-service rules require a driver to forward the record of duty status and supporting documents to the home terminal within 20 days, and the carrier to deposit them at its principal place of business within 30 days and keep them chronologically for each driver for at least 6 months. They also prohibit anyone from tampering with an ELD so that it does not accurately record and retain the required data — which is a constraint on what an integration may write back.
Fuel tax. Ontario requires IFTA records be kept for four years from the return due date or filing date, whichever is later, with distance records showing odometer or hubodometer readings at each jurisdiction’s border and distance travelled in each jurisdiction. An integration that drops jurisdiction crossings has broken a filing, not a feed.
Privacy. An integration that copies driver location history into a second system has extended the reach of employee personal information. PIPEDA applies to personal information about an employee collected, used or disclosed in connection with the operation of a federal work, undertaking or business, requires that it be retained only as long as necessary for the purposes for which it was collected, and requires an organisation to report to the Privacy Commissioner any breach of security safeguards where there is a real risk of significant harm. The second copy needs a retention rule too.
Cross-border. If the integration files advance data, the deadline is the CBSA’s: highway carriers must have data received and validated at least one hour before arrival, against published timeframes of air 4 hours, highway 1 hour, marine 24 hours, rail 2 hours. The CBSA supports transmission by electronic data interchange as well as through the eManifest Portal, developed primarily for small and medium-sized businesses.
A 30-truck carrier connects its TMS to its telematics platform so that arrival and departure times populate load records automatically, ending manual check calls.
Scope: one direction (telematics to TMS), one trigger (geofence entry and exit), three fields (event type, timestamp, vehicle). Key: the vehicle unit number, which already exists in both systems — the first genuine decision, and the one that makes everything else work.
The failure modes that appeared in testing: a geofence around a large yard fired twice, so the TMS needed to ignore a second arrival within an hour; the telematics timestamps were UTC and the TMS displayed local, producing arrivals an hour before departure across a change in offset; and one truck had a different unit number in each system, which surfaced only because the reconciliation report counted unmatched events.
None of that is exotic. All of it is what “a few days of work” actually contains, and it is why the reconciliation report is worth building before the integration goes live rather than after.
For customer-facing freight, many shippers still exchange transaction sets by EDI rather than REST, and the CBSA itself lists electronic data interchange as a transmission option for commercial trade data. A carrier will often run both: EDI to large shippers, REST APIs to its own tooling. Ask any TMS vendor which transaction sets it supports and whether they are native or brokered through a third party, because the answer changes your onboarding time with a new customer significantly.
Usefully in three places: drafting the field mapping from two schemas for a human to correct, generating the reconciliation queries that catch unmatched records, and reading the unstructured half of the traffic — the emailed rate confirmation, the scanned document — into the structure the API expects.
It does not own the integration. Field ownership, retention and what happens on conflict are decisions with regulatory consequences. Draft with AI; decide and sign as a person.
Days of coding, weeks of agreeing. Estimate by counting fields and decisions, not endpoints.
Use the mechanism the vendor built for synchronisation — a change feed or webhooks. Polling a query endpoint to simulate a feed is how you meet a rate limit; Samsara documents a 429 response with a Retry-After header for exactly that case.
Price it against the clerical hours it removes, and read the termination clause. Your records must remain electronically readable for six years whether or not you are still a customer.
Not in a way that alters recorded driving data. The regulations prohibit tampering with an ELD so that it does not accurately record and retain required data and prohibit entering inaccurate information into a record of duty status.
A 30-minute call is enough to tell you whether AI pays for itself in your back office.
