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
- You have your credentials and know the basics of reading. See External API: start here, credentials and your first call and External API: reading data (filters, pagination, limits, keeping in sync and errors).
- A write needs its own grant. OpenRoad grants an application each endpoint and action on its own, so a grant to read an endpoint does not allow you to write to it. Without the grant the call answers 403.
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:
| Record | Call | Wrapper | Example of what you send |
|---|---|---|---|
| Note on a load, driver, truck or trailer | POST /loads/:id/notes and the same under /drivers, /trucks and /trailers | note | {"note": {"content": "Arrived at shipper"}} |
| Note on a customer or an accident | POST /customers/:id/notes, POST /accidents/:id/notes | see the documentation | see the documentation |
| Safety note of a driver | POST /drivers/:id/safety_notes, PATCH on one note | safety_note | {"safety_note": {"comment": "...", "note_date": "..."}} |
| Load | POST /loads, PATCH /loads/:id | load | {"load": {"status": "closed"}} |
| Stop of a load | PATCH /destinations/:id | destination | {"destination": {"time_in": "2026-10-01T14:05:00Z"}} |
| Money of a load | PATCH /load_financials/:id | load_financial | {"load_financial": {"linehaul_rate": "1000.00"}} |
| Billing status of a load (the load id) | PATCH /load_billing_statuses/:id | load_billing_status | {"load_billing_status": {"status": "billed"}} |
| Carrier of a load (the load id) | PATCH /load_carrier_assignments/:id | load_carrier_assignment | {"load_carrier_assignment": {"vendor_id": 42}} |
| Service failure of a stop (the stop id) | PATCH /destination_service_failures/:id | destination_service_failure | {"destination_service_failure": {"reason": "accident"}} |
| Status of a load tender (the tender id) | PATCH /load_tender_statuses/:id | load_tender_status | {"load_tender_status": {"status": "accepted"}} |
| Load manager, customer manager | PATCH /load_managers/:id, PATCH /customer_managers/:id | load_manager, customer_manager | {"load_manager": {"csr_manager_id": 1042}} |
| Truck, trailer | PATCH /trucks/:id, PATCH /trailers/:id | truck, trailer | {"trailer": {"needs_repair": false}} |
| Cost and lease of a truck or trailer | PATCH /truck_financials/:id, PATCH /trailer_financials/:id | truck_financial, trailer_financial | {"truck_financial": {"cost": "85000.00", "lease_start": "2026-01-15"}} |
| Customer | PATCH /customers/:id | customer | {"customer": {"available_balance_limit": 50000.0}} |
| Place | PATCH /places/:id | place | {"place": {"name": "North Yard", "tags": ["terminal"]}} |
| Trailer location | POST /trailer_locations, PATCH /trailer_locations/:id | trailer_location | {"trailer_location": {"trailer_id": 502, "place_id": 2231, "status": "empty", "start_date": "2026-11-07T08:30:00-06:00"}} |
| Load flag | POST /load_flags | load_flag | {"load_flag": {"load_id": 123, "unscheduled": true}} |
| Region plan period | POST /region_plan_periods | region_plan_period | {"region_plan_period": {"region_id": 12, "valid_from": "2026-10-12", "valid_to": "2026-10-18", "days": [{"weekday": 1, "plan": 100}]}} |
| Lane bid | POST /lane_bids | lane_bid | {"lane_bid": {"customer_id": 42, "lanes": [ ... ]}} |
| Driver availability | POST /availability_events | see the documentation | see the documentation |
| Documents | POST under loads, drivers, trucks, trailers and customers | none: a file upload | Part 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_typeis required. It decides where the file appears in OpenRoad TMS. For a load it is one ofrate_confirmation(Rate Confirmation),bill_of_lading(Proof of Delivery),bol(Bill of Lading),lumper_receipt(Lumper Receipt),scale_ticket(Scale Ticket) andother(Other). For a driver it is the folder of the driver's Files tab, such ascdl,mvr,inspectionsortraining_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.
- Read the document.
- Fetch its
urlexactly 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
idand 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
Authorizationheader when it follows the redirect. - The link works more than once until it expires.
- A document with no stored file has
urlandurl_expires_atset tonull.
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
{"truck": { ... }}. Check that you send JSON with Content-Type: application/json.multipart/form-data call.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