Skip to main content
The OpenWrench Buyer API gives facility operators programmatic access to everything on the buyer side of the platform. You can use it for creating and tracking work orders, managing assets and locations, reviewing quotes and invoices, monitoring preventive maintenance, and querying your supplier network.

Base URL

All buyer endpoints are under /v1/buyer/.

Authentication

Every request must carry two headers: X-API-KEY (your API key, issued per buyer contact) and OW-KEY (the OpenWrench shared secret issued alongside it). The key automatically scopes every request to your company, so you only ever see your own data. Requests missing either header return 401.
To get an API key and shared secret, contact support@useopenwrench.com. Use GET /v1/buyer/me to inspect the identity (contact, facility, company) behind your key. Keys do not expire on their own. To rotate one, request a new key/shared-secret pair from support, deploy the new pair, then ask support to revoke the old one.
The Internal Teams API section further down this tab uses a separate partner API key. Your buyer key will not authenticate against those /v1/partners/ endpoints. See the Internal Teams API introduction for details.

Rate limits

10 requests per 20-second window per key. Beyond that you’ll receive 429 Too Many Requests. Wait at least 20 seconds before retrying, and space background jobs (such as full paginated exports) so they stay under the cap.

Keeping work orders in sync

If your integration mirrors work orders into another system (a ticketing tool, an ERP, a data warehouse), build it on push, not polling:
  1. Register a webhook endpoint. OpenWrench sends workorder.create, workorder.status_update, and workorder.new_note events as they happen.
  2. On each event, fetch that one work order with GET /v1/buyer/work_order/work_orders/{id}.
  3. Use GET /v1/buyer/work_order/work_orders for ad-hoc queries, the one-time initial load, and occasional reconciliation, with a narrow filter and a small page.
Do not poll the list endpoint on a schedule to find new or changed work orders. It is the most expensive read in the API, it is slow on large accounts, and it competes with your real work for the rate limit. See Work orders for the details.

Response envelope

Single-entity responses:
List responses add a total count:
Errors:
401 means a missing or invalid key; 400 covers bad input, bad filters, and permission denials; 429 is the rate limit.

Pagination and filtering

List endpoints accept offset, limit (default 10, max 25), sort_by, and order (asc | desc). The API treats additional query parameters as filters. Each endpoint supports its own set of filter keys, and keys it does not recognize are ignored rather than rejected. Multi-value filters use a plural key with comma-separated values (statuses=Unassigned,PendingApproval). For work orders, see the filter reference.

Date formats

Most timestamps are ISO 8601 strings with offset (for example, 2026-08-14T13:05:22.000-07:00); some database timestamp fields serialize as yyyy-MM-dd HH:mm:ss.S. Plain dates are yyyy-MM-dd. When sending date-times, use ISO 8601. Date filters on the invoice, proposal, and work order lists are the exception. They take MM/dd/yyyy HH:mm:ss, a local wall-clock time with no offset, for example 10/09/2026 00:00:00:
  • Time zone. Pass the optional timezone query parameter to set the zone OpenWrench reads the values in. Use an IANA zone name, such as America/Chicago, America/New_York, or UTC. Names are case-sensitive. Without timezone, OpenWrench reads values in UTC.
  • Rejected zones. Fixed offsets (-05:00, GMT-5, Z, Etc/GMT+5), abbreviations (CST), and unknown names return 400.
  • No offset in the value. OpenWrench ignores an offset such as -05:00 at the end of a filter value. Use timezone instead.
  • Malformed values return 400. A value that doesn’t match the format returns 400, for example Invalid markedPaidAtStartDate. 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.
  • End bounds. Invoice and proposal end dates cover the whole end day: OpenWrench replaces the time with 23:59:59 on that date in timezone. Work order end dates are exact, so send 23:59:59 to include the whole day.
  • Daylight saving time. A time in the skipped hour of a spring-forward change moves forward by the length of the gap. A time in the repeated hour of a fall-back change means the standard-time occurrence, which is the second one.
For example, this request returns invoices marked paid on October 9, 2026, Central time:
For each list’s filters, see the filter value rules for work orders, invoices, and proposals.

Detailed guides

The guides in this tab walk each part of the API in depth, with payloads, status models, and integration patterns:

Work orders

Create, filter, reassign, close out. Status model, notes, and problem types.

Webhooks

Work order created, status changed, and new note events pushed to your endpoint.

Service calls

Visit evidence: work logs, true work time, and technician details.

Assets & locations

Locations, regions, asset types, models, meters, and refrigerant tracking.

Invoices

The approval pipeline, AP sync, flattened exports, and bulk updates.

Quotes & proposals

Read supplier quotes and reconcile them against invoices.

Planned maintenance

Read schedules, skip runs, and drive PM from an external scheduler.

Supplier network

Query your network and rank private-network suppliers for dispatch.

Site surveys

Walkthroughs and the work orders cut from their findings.

Files & attachments

Upload once, reference everywhere, download evidence.

Account & utilities

Ping, key identity, user provisioning, and exchange rates.