External API: writing data and files (bodies, what can be updated, uploads and downloads)

Modified on Fri, 20 Nov at 11:27 AM

Besides reading, the External API can create and update some records, add notes and upload documents. This article shows how to send a write, which records you can change, how to upload a file, and how to download one.

Before you begin

Part 1: Send a write

A write is a POST (create) or a PATCH (change). Send the data as JSON, inside a wrapper named after the record, in the singular. For example, to mark a truck out of service:

curl -X PATCH "https://app.openroadtms.com/api/ext/v1/trucks/42" \
     -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"truck": {"oos": true, "oos_note": "Brake inspection"}}'

Always send the wrapper. A form body without it is refused with 400, bad_request. A JSON body without it is wrapped for you only when its keys are fields of the record, so do not rely on that.

The answer has the usual three parts. When something is wrong with the data, it is a 422, validation_error, with one entry in error.details for each field: { field, code, message }. See the error table in External API: reading data (filters, pagination, limits, keeping in sync and errors).

Part 2: What you can write

These are the writes, and the wrapper each one uses:

RecordCallWrapperExample of what you send
Note on a load, driver, truck or trailerPOST /loads/:id/notes and the same under /drivers, /trucks and /trailersnote{"note": {"content": "Arrived at shipper"}}
Note on a customer or an accidentPOST /customers/:id/notes, POST /accidents/:id/notessee the documentationsee the documentation
Safety note of a driverPOST /drivers/:id/safety_notes, PATCH on one notesafety_note{"safety_note": {"comment": "...", "note_date": "..."}}
LoadPOST /loads, PATCH /loads/:idload{"load": {"status": "closed"}}
Stop of a loadPATCH /destinations/:iddestination{"destination": {"time_in": "2026-10-01T14:05:00Z"}}
Money of a loadPATCH /load_financials/:idload_financial{"load_financial": {"linehaul_rate": "1000.00"}}
Billing status of a load (the load id)PATCH /load_billing_statuses/:idload_billing_status{"load_billing_status": {"status": "billed"}}
Carrier of a load (the load id)PATCH /load_carrier_assignments/:idload_carrier_assignment{"load_carrier_assignment": {"vendor_id": 42}}
Service failure of a stop (the stop id)PATCH /destination_service_failures/:iddestination_service_failure{"destination_service_failure": {"reason": "accident"}}
Status of a load tender (the tender id)PATCH /load_tender_statuses/:idload_tender_status{"load_tender_status": {"status": "accepted"}}
Load manager, customer managerPATCH /load_managers/:id, PATCH /customer_managers/:idload_manager, customer_manager{"load_manager": {"csr_manager_id": 1042}}
Truck, trailerPATCH /trucks/:id, PATCH /trailers/:idtruck, trailer{"trailer": {"needs_repair": false}}
Cost and lease of a truck or trailerPATCH /truck_financials/:id, PATCH /trailer_financials/:idtruck_financial, trailer_financial{"truck_financial": {"cost": "85000.00", "lease_start": "2026-01-15"}}
CustomerPATCH /customers/:idcustomer{"customer": {"available_balance_limit": 50000.0}}
PlacePATCH /places/:idplace{"place": {"name": "North Yard", "tags": ["terminal"]}}
Trailer locationPOST /trailer_locations, PATCH /trailer_locations/:idtrailer_location{"trailer_location": {"trailer_id": 502, "place_id": 2231, "status": "empty", "start_date": "2026-11-07T08:30:00-06:00"}}
Load flagPOST /load_flagsload_flag{"load_flag": {"load_id": 123, "unscheduled": true}}
Region plan periodPOST /region_plan_periodsregion_plan_period{"region_plan_period": {"region_id": 12, "valid_from": "2026-10-12", "valid_to": "2026-10-18", "days": [{"weekday": 1, "plan": 100}]}}
Lane bidPOST /lane_bidslane_bid{"lane_bid": {"customer_id": 42, "lanes": [ ... ]}}
Driver availabilityPOST /availability_eventssee the documentationsee the documentation
DocumentsPOST under loads, drivers, trucks, trailers and customersnone: a file uploadPart 3

For the fields each call accepts, and the values they take, open the interactive documentation (the link is in the first article).

Part 3: Upload a file

An upload is a multipart/form-data call with the file and a type. It is not JSON, and the file is not sent as base64 text. This call adds a bill of lading to a load:

curl -X POST "https://app.openroadtms.com/api/ext/v1/loads/42/documents" \
     -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
     -F "file=@/path/to/bol.pdf" \
     -F "upload_type=bol"

The same rules hold for the documents of loads, drivers, trucks, trailers and customers:

  • Largest file: 25 MB.
  • File types: PDF, JPG, JPEG, PNG, DOC, DOCX, XLS, XLSX, CSV and TXT.
  • upload_type is required. It decides where the file appears in OpenRoad TMS. For a load it is one of rate_confirmation (Rate Confirmation), bill_of_lading (Proof of Delivery), bol (Bill of Lading), lumper_receipt (Lumper Receipt), scale_ticket (Scale Ticket) and other (Other). For a driver it is the folder of the driver's Files tab, such as cdl, mvr, inspections or training_certificates. The documentation lists the values for each record.
  • A file you upload to a load is accepted at every load status, closed included.
  • Some driver document types need their own grant. You see and upload only the types your application has been granted.

A file that is too big, of a wrong type, or without an upload_type is refused with 400, bad_request, and the details name the field (file or upload_type).

Part 4: Download a file

A document, in a list or when you retrieve it, has two fields: url and url_expires_at. Your application sees them only when OpenRoad granted them.

  1. Read the document.
  2. Fetch its url exactly as it is. You do not need to send your credentials to it.

Keep these points in mind:

  • The link works for one hour. Do not store it, and do not log it: for that hour, anyone who has it can open the file. Keep the document id and read the document again when you need a new link.
  • After the hour, the link answers 410, link_expired. Read the document again to get a new link. A link that is more than a day old answers 404.
  • Do not send your credentials to the link. The link needs none, and a request that carries them is refused. Set your HTTP client not to pass an Authorization header when it follows the redirect.
  • The link works more than once until it expires.
  • A document with no stored file has url and url_expires_at set to null.

Download limits

Downloads have their own limits, apart from the request limits in Part 4 of External API: reading data (filters, pagination, limits, keeping in sync and errors). Each application may download at most 2 times the same document and 30 times any documents in one minute. Over it, the answer is 429, rate_limited, with Retry-After: 60. A download carries no X-RateLimit headers. The limits cover the file link of a document, a driver document, a fuel surcharge matrix, a driver pay statement, a load invoice and a load Full PDF. The link of a driver's photo has no limit.

FAQ

My write is refused with 400.
Check the wrapper: the data must be inside the record's name, such as {"truck": { ... }}. Check that you send JSON with Content-Type: application/json.
My write is refused with 403.
Your application has the grant to read the endpoint, but not to write to it. Contact help@openroadtms.com and say which call you need.
Can I upload a file as base64 text?
No. Use a multipart/form-data call.
My download link answers 410.
It has expired. Read the document again and use the new link.
Where do I see that my application made a change?
In OpenRoad TMS the change is recorded under your application name followed by " - API". See the first article.

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