Build recall screening into listing workflows.

Quickstart

Make your first recall match request.

Send a product name at minimum. Better inputs, especially brand, UPC, model, lot code, and category, usually produce clearer match scores.

curl "$RECALLWATCH_API_URL/v1/recalls/match" \
  -H "Authorization: Bearer $RECALLWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productName": "Jif peanut butter 16 oz",
    "brand": "Jif",
    "lotCode": "1274425",
    "category": "food",
    "liveCheck": true
  }'

Authentication

Use bearer API keys from your backend.

API keys should be used server-side. Do not place production keys inside frontend apps, mobile binaries, public repositories, query strings, or screenshots.

Authorization: Bearer cr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /v1/recalls/match

Check one product, listing, or catalog row.

The match endpoint normalizes submitted fields, searches connected recall data, scores candidates, and returns the strongest matches with reasons your team can review.

productName

Required. Product title, listing title, or catalog name.

brand

Recommended. Improves precision and reduces unrelated matches.

upc

Optional. Used when source data exposes a matching identifier.

model

Optional. Important for consumer products, appliances, and baby gear.

lotCode

Optional. Important for food and batch-specific recalls.

liveCheck

Optional boolean. Runs a live openFDA fallback for food inputs.

{
  "status": "needs_lot_verification",
  "topConfidence": 0.82,
  "matches": [
    {
      "source": "openFDA",
      "title": "Example peanut butter recall",
      "matchedFields": ["brand", "product_name"],
      "matchConfidence": 0.82,
      "recommendedAction": "verify_lot_or_date_code",
      "sourceUrl": "https://api.fda.gov/food/enforcement.json"
    }
  ],
  "warning": "Verify against the official recall notice before taking action."
}

Response interpretation

Status values are review guidance, not final safety decisions.

no_match

No matching recall was found in connected sources.

possible_match

A meaningful candidate was found and should be reviewed.

likely_match

A strong candidate was found and should be verified against the source.

needs_lot_verification

Product details match, but lot, date, or code information is needed.

Search and recent recalls

Explore connected recall records.

Use search for human-readable lookup and recent recalls for monitoring what has been imported most recently.

GET /v1/recalls/search?query=peanut+butter
GET /v1/recalls/recent?source=openFDA&limit=25
GET /v1/recalls/{recallId}

Source freshness

Show which datasets were checked.

Source summaries expose connected datasets, sync time, freshness state, and coverage notes. This is useful in dashboards and review queues where users need context.

GET /v1/recalls/sources

Usage

Track API activity by billing period.

Usage endpoints return monthly API calls used, remaining included calls, plan context, billing-period dates, and event breakdowns for the authenticated customer.

GET /v1/usage

{
  "plan": {
    "name": "developer",
    "includedApiCalls": 15000
  },
  "apiCalls": {
    "used": 42,
    "remaining": 14958
  },
  "usage": {
    "recall_check": 40,
    "recall_search": 2
  }
}

Errors

Errors use a consistent JSON envelope.

{
  "error": {
    "code": "invalid_product_input",
    "message": "productName is required.",
    "status": 400
  }
}

Safety language

Never present a no-match result as a safety guarantee.

CatalogRecall API is an automated matching layer. Results may be incomplete, delayed, or ambiguous. Always verify possible matches against official source notices before taking action.