> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.useopenwrench.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Supplier API

> Programmatic access for service providers: receive work orders, schedule service calls, submit quotes and invoices, pull WrenchMode data, and manage inventory.

The OpenWrench Supplier API gives service providers programmatic access to their side of the platform: receiving and updating work orders, scheduling and documenting service calls, submitting quotes and invoices, pulling WrenchMode technician time data, and managing purchasing and inventory.

## Base URL

```text theme={null}
https://api.useopenwrench.com/api/external
```

All supplier endpoints are under `/v1/supplier/`.

## Authentication

Every request must carry **two headers**: `X-API-KEY` (your API key, issued per supplier contact) and `OW-KEY` (the OpenWrench shared secret issued alongside it). The key automatically scopes every request to your facility — you only ever see work orders, invoices, and data that belong to you. Requests missing either header return `401`.

```bash theme={null}
curl -H "X-API-KEY: <your-key>" -H "OW-KEY: <shared-secret>" \
  "https://api.useopenwrench.com/api/external/v1/supplier/ping"
```

To get an API key and shared secret, contact [support@useopenwrench.com](mailto:support@useopenwrench.com).

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.

## 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

Most supplier integrations exist to mirror the OpenWrench work order queue into another system. Build that on push, not polling:

1. Register a [webhook](/supplier-api/webhooks) 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/supplier/work_order/work_orders/{id}`.
3. Use `GET /v1/supplier/work_order/work_orders` only for the one-time initial load and for 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. It is the most expensive read in the API, it is slow on large queues, and it competes with your real work for the rate limit. See [Work orders](/supplier-api/work-orders#reading-your-queue) for the details.

## Response envelope

Single-entity responses:

```json theme={null}
{ "type": "WorkOrder", "data": { "...": "..." }, "status": "ok" }
```

List responses add a total `count`:

```json theme={null}
{ "type": "WorkOrder", "data": [ "..." ], "count": 42, "status": "ok" }
```

Errors:

```json theme={null}
{ "message": "Human-readable message", "type": "NotFoundException", "status": "error", "traceId": "abc123def45" }
```

`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`). Additional query parameters are treated as field filters — pass a field name with a value (comma-separate multiple values) to filter the result set. Each endpoint's reference page lists its notable filters.

## Date formats

Most timestamps are ISO 8601 strings with offset (e.g. `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 with a `T` between the date and time and an explicit offset. A space-separated value such as `2026-09-10 10:43:00+00:00` is not ISO 8601 and is rejected; send `2026-09-10T10:43:00.000+00:00` instead. UTC may be written as `+00:00` or `Z`.

## Technician time data

The WrenchMode endpoints expose per-technician work and drive time: `GET /v1/supplier/wrench_mode/events/analytics/{fromDate}/{toDate}` returns a per-technician drive/work/total rollup (window capped at 1 month), and `GET /v1/supplier/wrench_mode/events` returns the raw event log behind it. Service-call expansions (`/with_work_logs`, `/with_tech_details`) give the per-visit story.

## Detailed guides

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

<CardGroup cols={2}>
  <Card title="Work orders" href="/supplier-api/work-orders" icon="clipboard-list">
    Receive, accept or decline, parts statuses, ECD, attachments, and notes.
  </Card>

  <Card title="Webhooks" href="/supplier-api/webhooks" icon="bolt">
    New work, status changes, and buyer notes pushed to your endpoint.
  </Card>

  <Card title="Service calls" href="/supplier-api/service-calls" icon="truck">
    Schedule, check in, check out, and set the completion status.
  </Card>

  <Card title="WrenchMode" href="/supplier-api/wrenchmode" icon="stopwatch">
    Per-technician analytics and the raw drive/work event log.
  </Card>

  <Card title="Quotes & invoicing" href="/supplier-api/quotes-and-invoicing" icon="file-invoice-dollar">
    Submit proposals, draft invoices, and publish with a PDF.
  </Card>

  <Card title="Purchasing & inventory" href="/supplier-api/purchasing-and-inventory" icon="boxes-stacked">
    Purchase requests to orders to receipts, catalogs, and stock.
  </Card>

  <Card title="Reference data" href="/supplier-api/reference-data" icon="map-location-dot">
    Buyer companies, locations, assets, and how data masking works.
  </Card>

  <Card title="Files & users" href="/supplier-api/files-and-users" icon="paperclip">
    The file store behind attachments, and technician provisioning.
  </Card>
</CardGroup>