Scope a recall

When a lot, a supplier or a part revision turns out to be bad, you need to know which finished units contain it and where each one is now. Recall answers that in one search.

You need the production:read permission to search.

Search in the app

Open Recall in the sidebar.
Choose how to search:
- By Lot: enter the lot number of a raw material. This is the lot recorded when the unit was built.
- By Supplier: choose a supplier. You find every unit built with parts received from that supplier.
- By Component Revision: choose a part, then one of its revisions. You find the units of that revision and everything built from them.
Select Search.

The page says how many affected units it found, or that it found none.

Read the results

The results include the finished units that the affected parts are built into, not only the parts themselves. For each unit the table shows the serial number, the part and revision, its status, and where it is now:

A commissioned device shows its device identifier, and its deployment status, fleet, customer and site.
A sub-assembly that is built into another unit shows which unit it is in.
A unit in stock shows its location.

Select a serial number to open the unit. See Serials.

Act on the units

Tick the units you want, or use the box in the table header to select all of them. Then use one of the buttons:

Export CSV saves the list as recall.csv, one row per unit, with where each unit is. It is useful for a customer notice or an authority.
Quarantine quarantines the selected units that are still in stock, which means AVAILABLE, RESERVED, WIP or RMA. You must give a reason. Other units are skipped and listed as not done. It needs the inventory:write permission.
Open rework orders opens one rework order for each selected unit. Choose the reason: RMA repair, where the unit comes back, or field service, where it is fixed where it is. It needs the service:write permission.

Quarantine and Open rework orders only appear for users who have the permission. Export CSV is always there.

After an action, the page searches again, so you see the new statuses.

Use the API

The search is GET /api/recall. Its operationId is recall. Send a bearer token with the production:read scope. The API base is your BuildTrace app address followed by /api.

The query parameters are lot, supplierId and revisionId:

curl "https://app.buildtrace.eu/api/recall?lot=LOT-2026-001" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

When you send more than one parameter, the API uses one of them:

If supplierId is set, it searches by supplier and ignores the others.
Otherwise, if lot is set and not empty, it searches by lot. If you also send revisionId, the search is narrowed to that revision.
Otherwise, if revisionId is set, it searches by component revision.

If you send none of them, the API returns 400 with the message “Search by a lot number, a supplier or a component revision.”

The response has serialIds, the IDs of the affected units, and affectedUnits:

{
  "serialIds": ["2f6c1c9e-8a53-4c1e-b6a5-0d7e4f1a9b32"],
  "affectedUnits": [
    {
      "serialId": "2f6c1c9e-8a53-4c1e-b6a5-0d7e4f1a9b32",
      "serialNumber": "SN-000123",
      "status": "SHIPPED",
      "partCode": "SENSOR-HUB",
      "revisionLabel": "B",
      "deviceIdentifier": "hub-0123",
      "deploymentStatus": "DEPLOYED",
      "fleetName": "North farms",
      "customerName": "Acme Farms",
      "deploymentLocation": "Barn 4"
    }
  ]
}

Each unit always has serialId, serialNumber and status. These fields are left out when they do not apply: partCode, partName, revisionLabel, locationCode, locationName, containedInSerialId, containedInSerialNumber, deviceIdentifier, deploymentStatus, fleetName, customerName and deploymentLocation.

To quarantine through the API, use quarantineSerial for each unit. To open a rework order, use createReworkOrder.