# Scope a recall

> Find every affected unit by lot, supplier or component revision, then act on them.

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

1. Open **Recall** in the sidebar.
2. 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.
3. 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](https://dev.buildtrace.eu/docs/concepts/serials.md).

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

```bash
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:

1. If `supplierId` is set, it searches by supplier and ignores the others.
2. Otherwise, if `lot` is set and not empty, it searches by lot. If you also send `revisionId`, the search is narrowed to that revision.
3. 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`:

```json
{
  "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`.