Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

Surface active recalls, safety notices, and health advisories for a product. Closient aggregates recalls from FDA (food, drug, device), FSIS (meat/poultry), CPSC (consumer products), and Health Canada, keyed by GTIN with optional batch/lot narrowing.

​
When to use

  • User scans a product and asks “is this safe?”
  • Before recommending a product in any other skill (find-alternative, plan-shopping-trip, etc.), do a recall check first.
  • Agent monitoring a user’s recently-purchased items.
  • When the scanned packaging encodes a batch/lot in GS1 AI 10 (a GS1 Digital Link of the form /01/{gtin}/10/{batch}), use the batch-specific endpoint so the answer is “is this lot under recall?” rather than “are any batches of this GTIN recalled?”.

​
Endpoints

​
GTIN-level lookup

GET /compliance/api/v1/products/{gtin}/recalls
  ?status=ONGOING|COMPLETED|TERMINATED|UNKNOWN
  &severity=CLASS_I|CLASS_II|CLASS_III
  &source_system=FDA|FSIS|CPSC|HEALTH_CANADA
Returns every open recall for the GTIN. Defaults to status=ONGOING to show live notices.

​
Batch/lot lookup (AI 10)

GET /compliance/api/v1/products/{gtin}/batches/{batch}/recalls
  ?status=ONGOING|COMPLETED|TERMINATED|UNKNOWN
  &severity=CLASS_I|CLASS_II|CLASS_III
  &source_system=FDA|FSIS|CPSC|HEALTH_CANADA
Returns only the recalls whose lot_codes field matches the supplied batch. Matching is case-insensitive and supports four patterns:
  • Exact: batch equals an entry in lot_codes (legacy strings, free-text token, or exacts array in the structured form).
  • Range: lot_codes includes a numeric or alphanumeric range like "lots 20261001 through 20261015" (free-text) or {"ranges": [["20261001", "20261015"]]} (structured). The scanned batch must be the same length as the endpoints and fall inside the inclusive range.
  • Wildcard: lot_codes includes a trailing-* pattern like "LOT-2026-*" or {"wildcards": ["LOT-2026-*"]}. Any batch whose case-insensitive prefix matches.
  • All-lots: a recall with an empty lot_codes field did not narrow to a subset of batches — every lot is considered affected and the recall is always returned.

​
Typical consumer scan flow

  1. Consumer scans a packaging QR encoding a GS1 Digital Link with AI 10: 
    https://id.closient.com/01/00012345678905/10/BATCH-2026-042
  2. Agent extracts gtin=00012345678905, batch=BATCH-2026-042.
  3. Agent calls: 
    GET /compliance/api/v1/products/00012345678905/batches/BATCH-2026-042/recalls
  4. If the response is empty, the specific lot is not under recall. Surface that explicitly (“No active recalls for lot BATCH-2026-042”) rather than silently proceeding.
  5. If the response contains recalls, surface them prominently — Class I first.
Direct scans of /01/{gtin}/10/{batch} in a browser hit the resolver, which routes the consumer through the recall interstitial when an open recall affects that specific batch (the same lot-matching logic powers both surfaces). The API endpoint above is for agents that want the structured response without the redirect dance.

​
Response

Array of recall records. Each has:
  • id — Closient short-UUID
  • title — short human description
  • status — ONGOING / COMPLETED / TERMINATED / UNKNOWN
  • severity — CLASS_I (most serious) / CLASS_II / CLASS_III
  • source_system — issuing agency
  • description — free-text narrative
  • hazard — what harm exposure could cause
  • remedy — what consumers should do
  • public_url — authoritative regulator URL
  • company_name — recalling firm
  • recall_date — when the regulator initiated the recall
  • jurisdictions — ISO 3166-1 alpha-2 country codes
  • created — when Closient first ingested the record

​
Severity at a glance

  • CLASS_I — reasonable probability of serious adverse health consequences or death. Surface prominently.
  • CLASS_II — temporary or medically reversible health effects.
  • CLASS_III — unlikely to cause adverse health effects; usually labeling violations.

​
Empty array

An empty response means no active recall for this GTIN (or, for the batch endpoint, no recall affecting that specific lot). Always worth saying explicitly (“No active recalls”) rather than silently proceeding.
  • resolve-gtin — get the product detail to display alongside the recall
  • find-alternative — if recalled, recommend a substitute