/v1/supplier/work_order/ for receiving jobs, responding to them, and keeping buyers informed while the work progresses. Scheduling visits and completing work happen through service calls.
All examples assume:
Reading your queue
The pattern that scales is push, then fetch by id:offset, limit default 10 max 25, sort_by, order). Every other query parameter is read as a filter from the filter reference below. Filters combine with AND, and everything is tenant-scoped to your facility.
The list and count resolve which work orders match in OpenWrench’s search index, then load the full records from the database. The count endpoint runs the same query as the list, so the two always agree. Behavior to know:
- Full-text search.
search=matches words (with prefix and stem matching) across the title, description, location name, notes, service call check-in and check-out notes, and problem type name. It also matches reference numbers such as the work order number, PO number, and asset serial number. Wrap the value in double quotes to require the exact phrase. - Sorting.
sort_bysupportscreatedAt,locationName,woPriority(by the priority’s expected resolution time), andlastServiceCallServiceScheduledAt. Any other value, or nosort_by, sorts bycreatedAtdescending. - Unrecognized filters are ignored. Only the keys in the filter reference below are supported. Any other query parameter is ignored rather than rejected, and the request still succeeds. That includes misspelled keys and
updatedAtStartDate,updatedAtEndDate,statusChangedAt,assignedAt,buyerFacilityId, andwalkthroughId, which are not in the search index. Before relying on a new filter, comparecount_bywith and without it. - Freshness. Search index and replica updates lag writes by a moment. Your own just-written change, or a work order assigned seconds ago, can be briefly absent from list results and counts.
- Pagination depth.
offset + limitcannot exceed the search result window of 10,000. Narrow the filter rather than paging that deep. - Data masking. If you are a third-party supplier (not a buyer’s internal service team), buyer-private fields are blanked on work orders, locations, and invoices before the response returns. Missing fields are usually masking, not bugs. See Reference data for details.
Filter reference
Keys are case-sensitive. A singular key (status) takes one value; the plural key (statuses) takes a comma-separated list and matches any of the values; notStatuses excludes every listed status. Date filters are explained under filter value rules.
Status
What and where
Who
Dates and deadlines
Filter value rules
- Use the plural key for several values.
statuses=TechScheduled,TechRescheduledmatches either status.status=TechScheduled,TechRescheduledlooks for one status with that literal name and returns nothing. - One value per key. If you repeat a parameter (
statuses=TechScheduled&statuses=TechRescheduled), only the first is used. Comma-separate the values instead. - Dates use
MM/dd/yyyy HH:mm:ss, for example08/01/2026 00:00:00. The value is a local wall-clock time, read in the zone you pass intimezone, or in UTC without it. The time is required, and both ends of a window are inclusive. End bounds are exact: OpenWrench doesn’t round them to the end of the day, so send23:59:59to include a whole day. URL-encode the value (curl -G --data-urlencodedoes this for you). Don’t add an offset such as-05:00to the value: OpenWrench ignores it. - A date that doesn’t parse returns
400withInvalid <key>. Expected format MM/dd/yyyy HH:mm:ss. That includes ISO 8601 values (2026-10-09T00:00:00), dates without a time (10/09/2026), and values of only spaces. OpenWrench still reads an empty value as 1 January 1970. timezonetakes an IANA zone name, such asAmerica/ChicagoorUTC. Fixed offsets (-05:00,GMT-5), abbreviations (CST), and unknown names return400. See Date formats for daylight saving time.- Booleans are
trueorfalse.unscheduledOrPastScheduleonly acts ontrue. - Values must be well formed. A non-numeric id, or a boolean other than
trueorfalse, can fail the request with a500rather than a400. - Tenant scoping can’t be overridden. The facility visibility applied from your API key always holds, whatever filters you pass.
00:00:00 and 23:59:59 on the same date along with your zone. This request returns work orders completed on October 9, 2026, Central time:
Accept or decline
Accept withPOST /v1/supplier/work_order/work_orders/status_update/confirm, which sets the status to ConfirmedByServiceProvider. A work order already in a completed or closed display status cannot be accepted (400).
POST .../status_update/decline. Only contacts of the work order’s assigned supplier facility may decline. The work order leaves your queue through the supplier-change flow: its status returns to PendingApproval, or a private-network supplier is auto-picked, depending on the buyer’s configuration. The note’s text is recorded as the decline reason and reflected in what the buyer sees, so make it specific.
Both calls take { "id": ..., "note": { ... } } and return the updated work order. id is the numeric work order id (an int64 that must exist), not the display woNumber string. Send it as a JSON number, not a quoted string. To check the value before you post, fetch it with GET /v1/supplier/work_order/work_orders/{id}.
There is no work order status_update endpoint for completing a job. You complete work through service call check-out.
Keep the buyer informed
Three lightweight signals while the job is in flight: Parts tracking. Three status endpoints, same{ id, note } body shape as above:
When internal teams can’t place work orders on hold
A buyer can stop its internal service team from putting work orders on hold. The per-team setting isallowToPlaceWorkOrdersOnHold. It is on by default, and the buyer can turn it off for an internal team.
When the setting is off, Supplier API keys that belong to that internal team cannot move a work order into an On Hold status. The On Hold statuses are WaitingForProposal, WaitingForProposalApproval, PartsRequested, PartsOnOrder, and DelayedByThirdParty. The block applies to:
POST .../status_update/parts_requestedandPOST .../status_update/parts_ordered.- Service call check-out and remote check-out with an On Hold
checkOutStatus.
403 and changes nothing:
- Moves within or out of On Hold. A work order that is already on hold can move to another On Hold status, such as
PartsRequestedtoPartsOnOrder. It can also leave On Hold, for example withparts_received. - Third-party suppliers. Keys of third-party suppliers are never restricted. Internal teams without the setting are not restricted either.
- Other flows. Work order creation, sub-contract statuses, and automatic flows such as requests for proposal and quotes are not affected.
PATCH /v1/supplier/work_order/work_orders/{id}/estimated_completion_date reads only estimatedCompletionDate (ISO 8601) from the body:
PATCH /v1/supplier/work_order/work_orders/{id}/append_supplier_attachments appends file references to supplierAttachments, preserving what is already there. Upload the file first (see Files and users), then:
Notes
Append to the shared buyer–supplier thread withPATCH /v1/supplier/work_order/work_orders/append_notes ({ "id": ..., "note": { "text", "noteAddedBy", "noteAddedAt" } }), and read a work order’s thread with GET /v1/supplier/work_order/work_order_notes/{woId}. Reading updates read receipts for your contact, and a denied read returns an empty list rather than an error.
To @mention people on the note, add taggedUsers beside the note: a list of contact email addresses. OpenWrench folds each email into note.elements as a user element, the same shape the apps write for an @mention. You don’t need to build the elements structure yourself. Tagged contacts are added to the work order’s subscriber list if they aren’t subscribed already.
taggedUsers:
- Emails are trimmed and lowercased before matching. A note can mention at most 25 users.
- Duplicate emails in the list, and users already tagged in
note.elements, are skipped rather than mentioned twice. - An entry that is not a valid email address, or a list of more than 25 emails, is rejected with a
400of typeinvalidInputDataException. Nothing is persisted. - An empty list is ignored. Sending
taggedUserswithout anoteobject is rejected with400.
PATCH /v1/supplier/work_order/work_orders/append_notes/bulk with { "id": ..., "notes": [ ... ] }. Each note must carry a photo URL and no other content: text must be empty and video, audio, otherFile, and elements must be absent. A request takes 1–25 notes, duplicate photo URLs are rejected with 400, and the batch keeps its order under one server-set noteAddedAt. Subscribers receive a single grouped notification instead of one notification per photo.
Labels
Work order labels are lightweight tags (a name plus an optional color) used to slice the queue. Through the API you can read the label catalog and replace the labels applied to a work order. Creating or editing the labels themselves stays in the OpenWrench app. Which catalog you see depends on your key. A key belonging to a buyer’s internal service team sees that buyer company’s catalog. A third-party supplier’s key sees its own facility’s catalog. Browse the catalog withGET /v1/supplier/work_order/work_order_labels, or fetch one with GET /v1/supplier/work_order/work_order_labels/{id}. The list is paginated 10 per page by default and accepts search and label filters on the label text. Pass no_pagination=true to pull the whole catalog in one call.
Replace a work order’s labels with PUT /v1/supplier/work_order/work_orders/{woId}/labels. The body is { "ids": [...] } and it is a full replacement: labels not listed are removed, and an empty array clears them all. The response lists the label mappings now active on the work order.
- Every id must be a live label from your own catalog; a missing or non-array
ids, a non-integer id, and unknown or cross-tenant ids are all rejected with400. - The write requires work order write permission: a key that can only see the work order (a bidder, or a facility with read-only visibility) gets
400. On an unassigned work order, only a facility with read-write visibility may label it. - An unknown, deleted, or foreign work order id answers the same
400as a denied write, not a404.
Create a supplier-initiated work order
Suppliers can open work orders themselves (a technician spots a broken door while on site for something else).POST /v1/supplier/work_order/work_orders requires title and locationId; the location determines the buyer facility and company.
problemTypeId falls back to the first leaf problem type of the location’s buyer company, and woPriorityId to a default priority for that company. An assetId, if given, must exist, and its area is inherited when areaId is not set. The field is needApproval (no “s”) on this create body. An id in the body is ignored: this call always creates a new work order.
The server sets the initial status. For a third-party supplier key, any status or isSupplierInitiated in the body is ignored. The server creates the work order as SupplierInitiatedPendingApproval with isSupplierInitiated: true. The buyer’s approval configuration then decides where it lands. When the buyer auto-approves supplier-initiated work orders, OpenWrench confirms it to your facility straight away as ConfirmedByServiceProvider. Otherwise, it stays in SupplierInitiatedPendingApproval until a buyer approves it. Two kinds of keys can set status: keys that belong to a buyer’s internal service team, and paying suppliers creating a work order at a location of a client they manage. When these keys omit status, OpenWrench derives the initial status from the buyer company’s configuration. An internal team lands in AssignedToInternalTech.
Internal team hand-offs. An internal service team key can create a work order for another supplier facility by sending that facility’s supplierFacilityId. This only works when your facility’s configuration allows transferring work. OpenWrench treats the create as a hand-off, just like a transfer. If the request sends no status, or sends SupplierInitiatedPendingApproval (as the contractor mobile app always does), OpenWrench seeds PendingConfirmationByServiceProvider. The work order goes to the destination provider to confirm instead of the buyer’s supplier-initiated approval queue. A private destination facility still maps to AssignedToInternalTech. OpenWrench keeps the status as sent in these cases:
- The request sends any other explicit
status. - The
supplierFacilityIdis your own facility. - Your facility’s configuration doesn’t allow transferring work.
Problem types
GET /v1/supplier/work_order/problem_types lists problem types across your related buyer companies (not rate limited). Use it to classify supplier-initiated work orders correctly per buyer.
Typical integration loop
- Register a webhook endpoint for
workorder.createandworkorder.status_update. On each delivery, fetch the work order by id. Do the one-time initial load from the list endpoint, and keep it out of the steady-state loop except as an infrequent, narrowly filtered safety-net poll. confirmordeclinewithin your SLA.- Schedule the visit via service calls; post parts statuses and an estimated completion date (ECD) as things develop.
- Complete via check-out, then bill via quotes and invoicing.