Skip to main content
For a supplier integration, the work order queue is the inbox. This guide covers the endpoints under /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

Do not build your integration on the list endpoint. GET /v1/supplier/work_order/work_orders is the most expensive read in the Supplier API. Polling it to discover new or changed work orders is the wrong pattern. It is slow on large queues, it burns your rate limit, and it still misses changes between polls. Use webhooks to learn that a work order was assigned to you, changed status, or received a note. Then fetch that one work order by id. Reserve the list for a one-time initial load and occasional reconciliation, with a narrow filter and a small page.
The pattern that scales is push, then fetch by id:
The list and count endpoints are for the two moments a webhook cannot cover. Use them for the first load of work that already existed before your endpoint was registered. Also use them for a periodic check that nothing was missed:
Standard pagination applies (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_by supports createdAt, locationName, woPriority (by the priority’s expected resolution time), and lastServiceCallServiceScheduledAt. Any other value, or no sort_by, sorts by createdAt descending.
  • 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, and walkthroughId, which are not in the search index. Before relying on a new filter, compare count_by with 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 + limit cannot 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,TechRescheduled matches either status. status=TechScheduled,TechRescheduled looks 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 example 08/01/2026 00:00:00. The value is a local wall-clock time, read in the zone you pass in timezone, 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 send 23:59:59 to include a whole day. URL-encode the value (curl -G --data-urlencode does this for you). Don’t add an offset such as -05:00 to the value: OpenWrench ignores it.
  • A date that doesn’t parse returns 400 with Invalid <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.
  • timezone takes an IANA zone name, such as America/Chicago or UTC. Fixed offsets (-05:00, GMT-5), abbreviations (CST), and unknown names return 400. See Date formats for daylight saving time.
  • Booleans are true or false. unscheduledOrPastSchedule only acts on true.
  • Values must be well formed. A non-numeric id, or a boolean other than true or false, can fail the request with a 500 rather than a 400.
  • Tenant scoping can’t be overridden. The facility visibility applied from your API key always holds, whatever filters you pass.
To match one local day, send 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 with POST /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).
Decline with 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 is allowToPlaceWorkOrdersOnHold. 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_requested and POST .../status_update/parts_ordered.
  • Service call check-out and remote check-out with an On Hold checkOutStatus.
A blocked call returns 403 and changes nothing:
What stays allowed:
  • Moves within or out of On Hold. A work order that is already on hold can move to another On Hold status, such as PartsRequested to PartsOnOrder. It can also leave On Hold, for example with parts_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.
Estimated completion date. PATCH /v1/supplier/work_order/work_orders/{id}/estimated_completion_date reads only estimatedCompletionDate (ISO 8601) from the body:
Attachments. 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 with PATCH /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.
Rules for 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 400 of type invalidInputDataException. Nothing is persisted.
  • An empty list is ignored. Sending taggedUsers without a note object is rejected with 400.
To post a batch of photos (a technician’s before/after set, for example), use 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 with GET /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.
Behavior to know:
  • 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 with 400.
  • 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 400 as a denied write, not a 404.

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.
Defaults when omitted: 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 supplierFacilityId is 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

  1. Register a webhook endpoint for workorder.create and workorder.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.
  2. confirm or decline within your SLA.
  3. Schedule the visit via service calls; post parts statuses and an estimated completion date (ECD) as things develop.
  4. Complete via check-out, then bill via quotes and invoicing.