External API: start here, credentials and your first call

Modified on Fri, 20 Nov at 11:27 AM

The OpenRoad TMS External API lets your own software read and update your OpenRoad TMS data: loads, drivers, trucks, customers and more. This article shows what you need, how to sign in, how to make your first call, how to find out which endpoints and fields your application may use, and what to do when you change your secret. The next two articles explain how to read data (External API: reading data (filters, pagination, limits, keeping in sync and errors)) and how to write data (External API: writing data and files (bodies, what can be updated, uploads and downloads)).

Before you begin

  • You need an application. An application is a pair of credentials, a client ID and a client secret, that belongs to your OpenRoad TMS account. To get one, contact help@openroadtms.com.
  • Each application sees only the data of your own account.
  • Use any tool that sends HTTPS requests: curl, Postman or the language of your software. The examples here use curl.

Part 1: The basics

  • Base address: https://app.openroadtms.com/api/ext/v1. Every endpoint path in the documentation is relative to it, for example /loads means https://app.openroadtms.com/api/ext/v1/loads.
  • Format: the API is a REST API. It answers in JSON.
  • The interactive documentation lists every endpoint, field and example, and lets you try calls: https://app.openroadtms.com/api-docs/ext/v1/index.html. These articles explain how to use the API. The documentation is the reference for each endpoint.

Part 2: Your credentials

  • Client ID: your application's user name.
  • Client secret: your application's password.

Treat the secret like a password. Keep it on your server, never in a web page or a mobile app, and never in code that other people can read. If you lose it or it gets exposed, contact help@openroadtms.com for a new one.

Part 3: Make your first call

1. Check that the API is up. The health endpoint needs no credentials:

curl https://app.openroadtms.com/api/ext/v1/health

You get this answer:

{
  "data":  { "status": "ok" },
  "error": null,
  "meta":  { "request_id": "...", "timestamp": "2026-04-14T12:00:00Z" }
}

2. Make a call with your credentials. Every other endpoint uses HTTP Basic authentication: your client ID is the user name and your client secret is the password. This call asks for one load:

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" "https://app.openroadtms.com/api/ext/v1/loads?per_page=1"

Every answer has the same three parts:

  • data: the records you asked for. It is null when there is an error.
  • error: what went wrong, with a code, a message and a details list. It is null when the call worked.
  • meta: a unique request_id and the time of the answer (UTC). A list answer also has page, per_page and total.

Keep the request_id of any call that fails. OpenRoad Support asks for it.

What the status codes mean:

  • 200: it worked.
  • 401 (unauthorized): the client ID or the secret is missing or wrong. Check them, and check that you did not paste a space or a line break.
  • 403 (forbidden): your application may not use this endpoint. See Part 4.

Part 4: Which endpoints and fields you can use

OpenRoad grants each application the endpoints it needs, and, for sensitive data, individual fields. Nothing is open by default.

  • An endpoint that is not granted answers 403, forbidden.
  • A field that is not granted is left out of the answer. It does not show as null: it is simply not there. Filtering or sorting on such a field fails with 400, invalid_filter or invalid_sort.

To find out what your application may use, probe it once when your software starts:

  • Endpoints: call each list endpoint with ?per_page=1. A 200 means it is granted, a 403 means it is not.
  • Fields: read one record and check whether the field is in it. A field that is missing is not granted.

Keep the result for the session, because grants change rarely. If you need more endpoints or fields, contact help@openroadtms.com.

Part 5: Change your secret without downtime

A secret can be replaced at any time. When it is, the old secret keeps working for 24 hours, so you can put the new one into your software before the old one stops. After 24 hours the old secret no longer works and calls with it answer 401.

Part 6: How your changes show in OpenRoad TMS

When your application creates or updates something, OpenRoad TMS records it under your application name followed by " - API". You see this name as the author of a note on a load, driver, truck, trailer or accident, in the history of a load (its stops, notes and documents) and in the changed by of a record.

Part 7: Versions

The version is part of the address: /api/ext/v1. Adding fields, filters or parameters to a version is not a breaking change and comes without notice, so make your software ignore fields it does not know. A breaking change comes as a new version, /api/ext/v2, with its own documentation.

Part 8: What you can reach

The API covers these areas. What your application may use depends on what OpenRoad granted it (Part 4).

  • Loads and stops, with their notes, documents, change logs, financials, invoices, gross profit, full PDF and scores.
  • Drivers, with notes, safety notes, documents, change logs, stats, pay statements, earnings summaries, scores, ETAs, availability and hours of service.
  • Trucks and trailers, with notes, documents, assignments, trailer locations and yards, financials and GPS logs.
  • Customers and billing data: customers, their notes and documents, billing settings, payroll schedules, compensations, fuel surcharge data, fuel card transactions and IFTA quarters.
  • Sales, regions and places: lane bids, award lanes, regions, region plans, capacity and places.
  • EDI: EDI documents, connection logs, errors and load tenders.

Open the interactive documentation to see the endpoints and fields of each area.

FAQ

I get 401. What do I check?
The client ID and the secret. They must be sent as HTTP Basic authentication, the client ID as the user name and the secret as the password. If you rotated the secret more than 24 hours ago, the old one no longer works.
I get 403. What does it mean?
Your application has not been granted that endpoint. Contact help@openroadtms.com and say which endpoint you need.
A field I expected is not in the answer.
Either the field does not exist, or your application has not been granted it. The API does not say which, on purpose. Contact help@openroadtms.com if you need the field.
Does the health endpoint need my secret?
No. It answers without credentials and does not count toward your request limits.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article