External API: reading data (filters, pagination, limits, keeping in sync and errors)

Modified on Fri, 20 Nov at 11:27 AM

Every list in the External API works the same way. This article shows how to filter, sort and page through a list, how many requests you may send, how to keep a copy of your data up to date without overloading OpenRoad TMS, and what every error means and what to do about it.

Before you begin

  • You have your credentials and made a first call. See External API: start here, credentials and your first call.
  • Your application must be granted the endpoint. A list you may not use answers 403.
  • The examples use paths relative to the base address https://app.openroadtms.com/api/ext/v1. Send them with your credentials.

Part 1: What a list answer looks like

A list endpoint, such as GET /loads, answers with the three parts you already know. For a list, meta also tells you where you are:

  • page: the page you got.
  • per_page: how many records a page holds.
  • total: how many records match your filters in all.
{
  "data":  [ { "id": 101, ... }, { "id": 102, ... } ],
  "error": null,
  "meta":  { "request_id": "...", "timestamp": "2026-04-14T12:00:00Z", "page": 1, "per_page": 25, "total": 1247 }
}

A few conventions of the data:

  • Times are UTC, in ISO 8601 form, for example 2026-04-14T12:00:00Z. Convert them to the user's time zone yourself.
  • Money, miles and percentages are text with decimals, for example "1234.56", so that no precision is lost.
  • A field with no value is null. A field your application may not use is not in the answer at all. Do not treat the two the same.
  • Related records are ids. A load holds a driver_id, not the driver. Read the driver on its own endpoint (Part 3).

Part 2: Filter, sort and page

Equal to one value:

?status=delivered
?customer_id=42

Equal to any of several values (use square brackets):

?status[]=delivered&status[]=billed

The brackets are required. If you send ?status=delivered&status=billed without them, only the last value counts. A client generated from the OpenAPI file sends the form without brackets, so add the brackets yourself for these filters. A filter takes up to 100 values. With more, the call fails with 400, invalid_filter, detail code too_many_values.

Greater or less than (a range):

?total[gte]=1000                 (1000 or more)
?total[gt]=1000                  (more than 1000)
?total[lte]=5000                 (5000 or less)
?total[lt]=5000                  (less than 5000)
?total[gte]=1000&total[lt]=5000  (from 1000 up to, not including, 5000)

Each endpoint's documentation says which fields accept which operators.

Sort, by one field at a time. It is ascending by default. Put a minus sign in front for descending:

?sort=created_at
?sort=-created_at

Pages:

?page=2&per_page=50
  • Defaults: page=1 and per_page=25.
  • The most per page is 100.
  • You have reached the end when page × per_page is at least meta.total, or when a page holds fewer rows than per_page.

You can combine everything:

?status[]=delivered&status[]=billed&total[gte]=1000&sort=-created_at&page=2&per_page=25

Fields you may not use. If your application is not granted a field, filtering or sorting on it fails with 400, invalid_filter or invalid_sort. Remove it from the request.

Part 3: Ask for less, ask smartly

Three rules keep your integration fast, and keep OpenRoad TMS fast for everybody:

  1. Ask for many records in one request, not one request per record. A filter takes up to 100 values and a page holds up to 100 rows. To read the drivers of 25 loads, collect the unique driver_id values and send GET /drivers?id[]=8421&id[]=8422&id[]=8423&per_page=100, not 25 calls. With more than 100 ids, send them in groups of 100.
  2. After the first full load, ask only for what changed. See Part 5.
  3. Limit the time range, and send one request at a time. Add a date filter such as app_date[gte]=2026-09-22 so that old history is not read again and again. Wait for each page before you ask for the next one, and never send pages or requests in parallel.

Some more habits that help:

  • To count records, do not download them. Ask for one record and read meta.total: GET /loads?status[]=picked_up&per_page=1.
  • Do the counting on your server, not in the browser, and keep the numbers for 5 to 15 minutes. Every open browser tab would send the same requests again.
  • Keep reference data a long time. Billing settings, payroll schedules, compensations, employees and users change rarely: keep them for hours. Customers, and active loads and drivers, for 5 to 15 minutes, then ask only for what changed.
  • Do not ask more often than every 5 minutes for the same list. Some lists are very large.

Part 4: Request limits

Every call with your credentials counts against two limits of your application: 12,000 requests a minute and 120,000 requests an hour. Each answer carries three headers about the window that has fewer requests left:

  • X-RateLimit-Limit: the limit of that window.
  • X-RateLimit-Remaining: how many requests you have left in it.
  • X-RateLimit-Reset: when the window ends, in epoch seconds.

When you pass a limit, the call answers 429, rate_limited, with a Retry-After header: the seconds until that window ends. Wait that long, then continue. The health endpoint does not count. File downloads have their own limits: see External API: writing data and files (bodies, what can be updated, uploads and downloads).

Part 5: Keep your data in sync

First load. Read the list once, in pages of 100, with a date filter, one page at a time, until a page holds fewer rows than per_page. Write down the time you started.

After that, ask only for the records that changed since your last run, sorted by when they changed:

GET /destinations?updated_at[gte]=2026-09-29T14:00:00Z&sort=updated_at&per_page=100

Keep the time you started this run for the next one. The data changes over minutes, not seconds, so run the sync every 5 to 15 minutes, not in a tight loop. A run usually needs only a few pages. If a run reaches page 100, check that the request carries the updated_at[gte] filter. A filtered run after a big update can go past page 100: keep reading until the results end.

Tip
A change you have just written may take a moment to show when you read it back. Do not wait for it in a tight loop.

Part 6: Errors

Every error answer has data set to null and an error with a code, a message and a details list. details is always there. For an error about a field, each entry is { field, code, message }, so you can show the problem next to the field. Keep the request_id from meta of every error: OpenRoad Support asks for it.

CodeHTTPWhat it meansWhat to do
unauthorized401The credentials are missing or wrong.Check the client ID and secret. Do not retry in a loop.
forbidden403Your application may not use this endpoint.Contact help@openroadtms.com and say which endpoint you need.
not_found404The record does not exist or is not in your account.Treat as empty. Do not retry.
bad_request400A required parameter is missing or has a wrong form.Fix the request.
invalid_filter400A filter is not valid. Look at details.Fix or remove the filter.
invalid_sort400You cannot sort by this field.Sort by another field.
validation_error422The data you sent failed the checks. Look at details.Fix the data. See External API: writing data and files (bodies, what can be updated, uploads and downloads).
link_expired410A file link has expired.Read the parent record again for a new link.
rate_limited429You passed a request limit.Wait for Retry-After seconds, then continue.
internal_error500A fault on the OpenRoad side.Retry up to 3 times, 1, 2 and 4 seconds apart. If it still fails, send OpenRoad Support the request_id.

The details[].code tells you what is wrong with one field:

Detail codeWhat it means
unknown_fieldThe field is not known for this call. It either does not exist, or your application has not been granted it. The API does not say which.
invalid_valueThe value has the wrong type, is not an allowed value, or has a wrong form.
unsupported_opThe operator is not allowed for this field, for example a range on a field that has none.
invalid_operatorThe range operator is not gt, gte, lt or lte.
missing_parameterA required parameter is missing.
too_many_valuesA multi-value filter has more than 100 values.

Do not retry a 4xx error: the request must change first. Reading data is safe to retry after a network failure.

Good to know

  • Your software should ignore fields it does not know. OpenRoad can add fields and filters to a version without notice.
  • Log the request_id, the error code, the HTTP status, the path and the time of every call. Never log the credentials or whole answers.

FAQ

Why do I get only one of the values I filtered on?
You sent the parameter twice without brackets. Use status[]=a&status[]=b.
How many records can I get in one call?
Up to 100. Use pages for more, one page at a time.
How do I count records without reading them?
Ask for one record with the same filters and read meta.total.
How often may I read a list?
Not more than every 5 minutes. After the first full load, ask only for what changed since your last run.
I got 429. What now?
Wait the number of seconds in the Retry-After header, then continue, with fewer and slower requests.

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