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

# Buyer companies, locations, assets, and data masking

> Read the buyer-side reference data suppliers can see: related buyer companies, locations and regions, assets and asset types, and how masking works.

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:

```bash theme={null}
export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"
export SECRET="<shared-secret>"
```

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

```bash theme={null}
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/buyer_company/buyer_companies"
```

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

```bash theme={null}
# List: page size is capped at 10 on this endpoint (larger limits are silently reduced)
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/location/locations?limit=10"

# Count, one, or several at once
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/count_by"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/1204"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/location/locations/multiple/1204,1205"
```

* 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.

```bash theme={null}
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/asset/assets?locationId=1204&limit=25"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/asset/assets/5511"
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" "$BASE/v1/supplier/asset/asset_types?limit=25"
```

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.

```bash theme={null}
# The catalog (internal service team keys only)
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/asset/asset_labels?no_pagination=true"

# Replace the labels on an asset
curl -X PUT "$BASE/v1/supplier/asset/assets/5511/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [7, 21] }'
```

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.