Skip to main content
Work orders reference a world owned by your buyers: their companies, locations, regions, and assets. The Supplier API exposes read-only views of all of them, filtered to what your relationships entitle you to see. All examples assume:

​
Data masking

How much you see depends on what kind of supplier your key belongs to:
  • Internal service team keys (your supplier company is the buyer’s own in-house team) receive full records.
  • Third-party supplier keys receive masked records on work orders, locations, and invoices: buyer-private fields are blanked before the response returns.
If a field you expect is consistently empty, masking is the first thing to check. The scoping itself cannot be widened by filters; tenant-security filters derived from your key always apply.

​
Buyer companies

GET /v1/supplier/buyer_company/buyer_companies returns every buyer company that has a relationship with your supplier. No pagination or filters are honored: the full tenant-scoped set comes back in one response (each company’s buyerCompanySettings is stripped).
Use it to key per-buyer behavior in your integration (which problem types to use, which buyers auto-approve third-party completions, and so on).

​
Locations and regions

  • The location list clamps limit to 10; most other lists allow 25.
  • multiple/{ids} silently drops ids you cannot read; the response count equals what was actually returned.
  • Regions (buyer-company groupings of locations) are at GET /v1/supplier/location/regions and /regions/{id} with standard pagination.

​
Assets and asset types

Assets are the equipment your technicians service; asset types classify them.
The single-asset read hydrates the asset’s meters (envelope type ApiAssetWithMeter), which gives your techs meter history context before a visit. All four endpoints (assets, assets/{id}, asset_types, asset_types/{id}) are read-only with standard pagination and field filters.

​
Asset labels

Asset labels are buyer-defined tags on assets (a name plus an optional color). They always belong to a buyer company, so access through the Supplier API is limited to keys of a buyer’s internal service team: those keys see their buyer company’s catalog, while a third-party supplier’s key gets an empty list.
The catalog is read-only (GET /v1/supplier/asset/asset_labels and /{id}); labels are created and edited in the OpenWrench app. The list is paginated 10 per page by default, accepts search and label filters on the label text, and no_pagination=true returns the whole catalog. PUT /v1/supplier/asset/assets/{assetId}/labels replaces the full set of labels on the asset ({ "ids": [...] }; an empty array clears them all) and returns the labels now active. The write requires asset write permission, and every id must be a live label of your buyer company’s catalog. A third-party supplier’s key gets 400 even when it holds asset write permission. An unknown, deleted, or foreign asset id answers the same 400 as a denied write, not a 404.

​
Caching strategy

Reference data changes slowly. A practical setup:
  • Refresh buyer companies daily (one call).
  • Sync locations and assets for active work orders on demand, caching by id.
  • Treat 400 on a single read as “outside your scope” and 404 as “does not exist”, and expect ids to disappear from your view when a buyer relationship ends.