# Product Safety & Recall Match API — match a product by barcode or title+brand against US FDA and EU recalls, with confidence scoring and brand recall watch

> Resolve a product (GTIN ‖ title+brand ‖ listing_url) and match it against FDA + EU recalls with transparent confidence. recalls[] = high-confidence (brand independently matched); possible[] = lower-confidence candidates.
> ReefAPI engine `enrich-recall` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/enrich-recall/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /enrich-recall/v1/product_match — 3 credits
Resolve a product (GTIN ‖ title+brand ‖ listing_url) and match it against FDA + EU recalls with transparent confidence. recalls[] = high-confidence (brand independently matched); possible[] = lower-confidence candidates.

**Parameters:**
- `gtin` (string, optional) — Product barcode (GTIN-8/12/13/14, UPC, EAN or ISBN). The engine resolves it to {title, brand, category} via the barcode engine, then matches recalls. Provide this OR (title + brand) OR listing_url.
- `title` (string, optional) — Product title/name. Use with `brand` when you have no barcode. Ignored if `gtin` resolves a product.
- `brand` (string, optional) — Product brand / manufacturer. STRONGLY recommended with `title` — brand is the independent false-match guard (a title match with a different brand is never asserted).
- `category` (string, optional) — Optional product category hint (food / drug / device / toy / apparel …) — improves category-fit scoring. Auto-derived from the barcode when available.
- `listing_url` (string, optional) — A marketplace product URL (amazon/ebay/…). MINIMUM support: the host is recorded and you must still pass title (+brand) for matching. Full URL→product resolution is the enrich-url engine's job.
- `max_results` (integer, optional, default 25) — Max recalls[] + max possible[] returned (each list capped at this).

**Returns:** identity{resolved_title,brand,category,gtin,source,resolved:bool}, recalls[]{match_confidence,matched_on[],components{brand,title,category,exact_id},agency,recall_id,classification,severity_score,recalling_firm,product,hazard,remedy,status,date,url}, possible[] (same shape, lower confidence), counts{recalls,possible,candidates_scored}, sources_searched[], coverage_gaps[], no_match_note

**Example request body:**
```json
{
  "gtin": "0860007279478"
}
```

### POST /enrich-recall/v1/brand_check — 2 credits
All recalls for a brand / recalling-firm (normalized passthrough of the recall engine's by_company), newest first — the seller-watch / due-diligence use case.

**Parameters:**
- `brand` (string, required) — Brand / recalling-firm name to list recalls for.
- `category` (string, optional) — FDA recall category scope (passed through to the recall engine). Default all. [one of: all, food, drug, device]
- `date_from` (string, optional) — Filter recalls with report date from this YYYY-MM-DD.
- `date_to` (string, optional) — Filter recalls with report date to this YYYY-MM-DD.
- `limit` (integer, optional, default 25) — Max recalls to return for the brand.

**Returns:** brand, recalls[] (normalized FDA recall records, newest first), total, has_more, sources_searched[], no_match_note

**Example request body:**
```json
{
  "brand": "Pfizer",
  "category": "drug",
  "limit": 3
}
```

### POST /enrich-recall/v1/batch — 2 credits
Scan up to 25 catalog products in one call (seller pre-listing audit). Each item is product_match'd; per-item ok/error + a roll-up summary.

**Parameters:**
- `items` (array, required) — Up to 25 products (seller-catalog scan). Each item = a {gtin} OR {title, brand[, category]} object (or a bare barcode string). Per-item ok/error; one bad item never sinks the batch.
- `max_results` (integer, optional, default 25) — Max recalls[] + max possible[] returned (each list capped at this).

**Returns:** results[] (one product_match payload per item, with input echoed), count, ok_count, flagged_count (items with >=1 recalls[] hit), no_match_note

**Example request body:**
```json
{
  "items": [
    {
      "title": "x0",
      "brand": "y"
    },
    {
      "title": "x1",
      "brand": "y"
    },
    {
      "title": "x2",
      "brand": "y"
    },
    {
      "title": "x3",
      "brand": "y"
    },
    {
      "title": "x4",
      "brand": "y"
    },
    {
      "title": "x5",
      "brand": "y"
    },
    {
      "title": "x6",
      "brand": "y"
    },
    {
      "title": "x7",
      "brand": "y"
    },
    {
      "title": "x8",
      "brand": "y"
    },
    {
      "title": "x9",
      "brand": "y"
    },
    {
      "title": "x10",
      "brand": "y"
    },
    {
      "title": "x11",
      "brand": "y"
    },
    {
      "title": "x12",
      "brand": "y"
    },
    {
      "title": "x13",
      "brand": "y"
    },
    {
      "title": "x14",
      "brand": "y"
    },
    {
      "title": "x15",
      "brand": "y"
    },
    {
      "title": "x16",
      "brand": "y"
    },
    {
      "title": "x17",
      "brand": "y"
    },
    {
      "title": "x18",
      "brand": "y"
    },
    {
      "title": "x19",
      "brand": "y"
    },
    {
      "title": "x20",
      "brand": "y"
    },
    {
      "title": "x21",
      "brand": "y"
    },
    {
      "title": "x22",
      "brand": "y"
    },
    {
      "title": "x23",
      "brand": "y"
    },
    {
      "title": "x24",
      "brand": "y"
    },
    {
      "title": "x25",
      "brand": "y"
    }
  ]
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=enrich-recall
- Human docs page: https://reefapi.com/docs/enrich-recall
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt