Food Recall Inventory Matcher

Compare an authorized retailer/distributor inventory CSV or JSON file against official openFDA food enforcement recall reports. Returns explainable, conservative candidate matches with FDA source links. No FDA API key.

Not legal, food-safety, medical or compliance advice. FDA recalls may be revised or delayed. Never treat this output as a clearance to sell or as a final determination that a particular lot is affected. This Actor is not sponsored or endorsed by the FDA.

Quick start

Supply exactly one of inventoryFiles (Apify upload UI, with a readable HTTPS URL), inventoryFileUrl (authorized HTTPS link), inventoryRows (inline JSON array), or inventoryStoreId (an authorized private Apify key-value store selected with READ permission). For private uploads, first upload the CSV/JSON file to your own Apify key-value store, then choose that store under Authorized inventory storage and enter its record key in Filename in selected storage (for example, INVENTORY.csv). Do not put Apify tokens in links. File-upload URLs from private stores cannot be read unless the Actor has explicit READ permission via the storage picker. UTF-8 CSV template:

row_id,product_name,brand,manufacturer,lot,barcode,sku
INV-001,Todd's Seeds Salad Sprouting Mixture,Todd's Seeds,TODD'S SEEDS LLC,TS-633-2,,SEEDS-01
INV-002,Unrelated Invented Cereal,Example Brand,Example Foods,LOT-XYZ,,

JSON Actor input example:

{
  "inventoryRows": [
    {"row_id":"INV-001","product_name":"Todd's Seeds Salad Sprouting Mixture","brand":"Todd's Seeds","manufacturer":"TODD'S SEEDS LLC","lot":"TS-633-2"}
  ],
  "matchThreshold": 0.75,
  "maxResults": 50,
  "maxMatchesPerRow": 3,
  "maxDataAgeDays": 21
}

Required customer fields: row_id (opaque inventory row identifier) and product_name. Optional: brand, manufacturer, lot, barcode, sku. File input supports CSV headers or an array of JSON objects (also an object with rows array). Maximum 1,000 rows and 3 MB of file content. All unknown columns are rejected. Never upload personal names, email addresses, addresses, telephone numbers, or any other personal data. Some personal contact patterns are rejected automatically, but customers remain responsible for excluding all personal data. Only rowId is copied from the customer's file into the output dataset; user input is stored by Apify according to the platform's storage/retention policies.

Matching and uncertain evidence

The Actor downloads every currently listed openFDA food/enforcement ZIP partition from the official FDA downloads manifest, for a complete snapshot on each run.

• strong_match: a very strong product-description match AND an exact inventory lot appearing in FDA code_info (or an explicit FDA all-lots statement). No conflicting manufacturer/recalling-firm or brand evidence. This is still a candidate match.
• review_required: the product appears related but the lot, brand, recalling firm, or evidence coverage cannot confirm scope. Lot and firm disagreements explicitly force manual review.
• no_match: no credible candidate was found in this FDA snapshot. This is NOT a finding that the product is safe or unaffected.

FDA recalling_firm is not necessarily the legal manufacturer of the product. FDA food enforcement records do not guarantee a separate structured UPC, SKU, or brand field; the Actor only marks these fields as matched if the published text supports them. Source product description and code information are passed through without inventing lot ranges. FDA report_date, recall_initiation_date, classification, recalling firm, and status are included only if present.

Every candidate provides the FDA recall number and an official openFDA record URL derived from that identifier. Unverified/missing lot or manufacturer evidence cannot produce a strong_match.

Output schema

The Apify default dataset contains records with rowId, matchStatus, confidenceLevel, confidenceScore, fdaRecallNumber, fdaEventId, productDescription, fdaCodeInfo, lotScope, fdaRecallingFirm, recallDate (FDA report_date), recallInitiationDate, classification, fdaStatus, sourceUrl, matchedFields, conflictingFields, reviewReasons, recordFingerprint, recordChangeStatus, fdaExportDate, chargeableEvent and disclaimer. Absent FDA fields remain absent/null; a no_match row has no recall ID or evidence URL.

The SUMMARY record in the default key-value store contains source export date, FDA record/partition counts, inventory row count, emitted/strong/review/no-match counts, charged event count, truncation flag, and payment-limit flag. The output limit may stop before all inventory rows are inspected; unprocessed rows are never silently marked no_match.

Track corrected or updated FDA records

FDA ZIP downloads are snapshots and old records can change. Every run downloads all partitions, rather than trying incremental updates. Each candidate includes a SHA-256 recordFingerprint of the original FDA JSON record. For comparisons between runs, pass previousResults with an array of objects containing ONLY recallNumber and recordFingerprint copied from prior outputs. The updated output reports recordChangeStatus: updated, unchanged, or not_compared. This does not prove a recall changed legal status or detect removed records that are no longer matched.

Transparent event billing

Active price: $0.01 per official-source-backed strong_match through the custom Apify Pay-per-event (PPE) event verified-match. The configured chargeable events list contains only verified-match, with neither automatic apify-actor-start nor apify-default-dataset-item charges. Ambiguous review_required results, no_match results, malformed input and source/network failures trigger no Actor PPE event charge. The Actor's current Apify Store pricing page is authoritative for the event price and any separate platform charges. Post-run data storage/access or Apify subscription fees may be subject to Apify's platform terms. Users can set a maximum charge per run.

Official source and licensing

• FDA ZIP exports and download strategy: https://open.fda.gov/apis/downloads/
• Official current partition manifest: https://api.fda.gov/download.json
• Food recall enforcement: https://open.fda.gov/apis/food/enforcement/
• openFDA licensing: https://open.fda.gov/license/
• openFDA terms: https://open.fda.gov/terms/
• Apify PPE monetization: https://docs.apify.com/actors/publishing/monetize/pay-per-event
• Apify Store publishing requirements: https://docs.apify.com/actors/publishing/publish

FDA materials on openFDA are generally CC0 unless otherwise stated. CC0 does NOT waive trademarks, patents, publicity, privacy, third-party copyright or specially restricted data. For example, GMDN terminology has a separate third-party license; this Actor uses only food enforcement data, never restricted medical-device classifications. FDA does not warrant completeness or accuracy. Do not claim government endorsement.

Quality controls

Run tests in the project root with:

python3 -m unittest discover -s tests -v

Tests include a real downloaded FDA record, a confirmed-text-and-lot candidate, conflicting lot and manufacturer, no match, changed source fingerprint, corrupt customer CSV/JSON, PII-field rejection and FDA archive completeness. ZIP test data under fixtures is never shipped in the Actor Docker image. Invalid or stale FDA datasets cause a safe failure without emitting misleading no_match output. No login, CAPTCHA bypass, secret source, proxy or API key is required.