Fairly Made API (3.0.0)

uniqueIdentifier convention

The uniqueIdentifier is your item's unique key in the Fairly Made system. It defines the granularity of analysis you want Fairly Made to perform: one uniqueIdentifier = one analysis.

For create payloads that include a uniqueIdentifier, start the value with a short resource prefix, then add your own reference segments separated by underscores (_) instead of spaces or concatenated camelCase where practical.

Use one of these prefixes depending on the entity: SUP (supplier), MAT (material), COMP (component), PACK (packaging), MP (manufactured product), PI (purchased item), FILE (file), BP (brand product). Each endpoint’s schema describes how to compose the segments after the prefix for that resource.

Entity references (id vs unique identifier)

When a schema exposes both a UUID field (*Id) and a client reference field (*UniqueIdentifier), send exactly one of them — not both, not neither. Violations return HTTP 400 (e.g. *ReferenceConflict, *ReferenceRequired, *BothIdAndUniqueIdentifier).

Owner (supplier) — on manufactured materials, components, and products: provide either ownerId or ownerUniqueIdentifier (with ownerKind = SUPPLIER), or an address instead — not both owner and address. ownerUniqueIdentifier requires ownerKind = SUPPLIER.

Purchased items — for the buyer, send exactly one of buyerId or buyerUniqueIdentifier (buyerUniqueIdentifier requires buyerKind = SUPPLIER). For the seller, send exactly one of sellerId or sellerUniqueIdentifier. For the purchased entity (material, component, or product), send exactly one of itemId or itemUniqueIdentifier. purchaseOrder is required. If you run traceability collection with Fairly Made, every purchased item needs at least a purchaseOrder so supplier data collection can be launched; if your analysis granularity is not at purchase-order level, use a representative PO for the panel covered by that granularity. If you are unable to provide a PO at all, you can set the value to NOT_SPECIFIED. Links made only through used items (usedMaterials, usedComponents, usedProducts, etc.) instead of purchasedItems are not taken into account for the analysis.

Brand products — include at most one product reference: exactly one of manufacturedProductId, manufacturedProductUniqueIdentifier, purchasedItemId, or purchasedItemUniqueIdentifier. For the warehouse supplier, send exactly one of supplierId or supplierUniqueIdentifier. For packaging, send either packagingIds or packagingUniqueIdentifiers, not both.

Manufactured items and their purchased items

When you run traceability collection with Fairly Made, each manufactured item must be created as a pair: the manufactured item and its corresponding purchased item. For a given item (manufactured material, manufactured component, or manufactured product), first create the manufactured item, then create the matching purchased item (POST /purchased-items) that references it and carries a purchaseOrder. Without this pair, supplier data collection cannot be launched for that item. If you handle traceability yourself, the purchased item stays optional.

Authentication

Authenticate with a Bearer access token (Authorization: Bearer <token>). Your registry context is resolved from the token.

Environments

Two environments are available — Production and Sandbox — each with its own base URL (see servers above). The documented paths and request/response schemas are identical; only the host changes. Use Sandbox for integration tests, Production for live data.