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=1andper_page=25. - The most per page is 100.
- You have reached the end when
page × per_pageis at leastmeta.total, or when a page holds fewer rows thanper_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:
- 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_idvalues and sendGET /drivers?id[]=8421&id[]=8422&id[]=8423&per_page=100, not 25 calls. With more than 100 ids, send them in groups of 100. - After the first full load, ask only for what changed. See Part 5.
- Limit the time range, and send one request at a time. Add a date filter such as
app_date[gte]=2026-09-22so 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.
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.
| Code | HTTP | What it means | What to do |
|---|---|---|---|
unauthorized | 401 | The credentials are missing or wrong. | Check the client ID and secret. Do not retry in a loop. |
forbidden | 403 | Your application may not use this endpoint. | Contact help@openroadtms.com and say which endpoint you need. |
not_found | 404 | The record does not exist or is not in your account. | Treat as empty. Do not retry. |
bad_request | 400 | A required parameter is missing or has a wrong form. | Fix the request. |
invalid_filter | 400 | A filter is not valid. Look at details. | Fix or remove the filter. |
invalid_sort | 400 | You cannot sort by this field. | Sort by another field. |
validation_error | 422 | The 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_expired | 410 | A file link has expired. | Read the parent record again for a new link. |
rate_limited | 429 | You passed a request limit. | Wait for Retry-After seconds, then continue. |
internal_error | 500 | A 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 code | What it means |
|---|---|
unknown_field | The 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_value | The value has the wrong type, is not an allowed value, or has a wrong form. |
unsupported_op | The operator is not allowed for this field, for example a range on a field that has none. |
invalid_operator | The range operator is not gt, gte, lt or lte. |
missing_parameter | A required parameter is missing. |
too_many_values | A 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
status[]=a&status[]=b.meta.total.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
Feedback sent
We appreciate your effort and will try to fix the article