{ "openapi": "3.0.2", "info": { "title": "Product Recall Check API", "description": "Check products, UPCs, NDCs, model numbers, companies, and keywords against normalized U.S. recall data.", "version": "1.0.0", "x-long-description": "Product Recall Check API helps e-commerce, compliance, marketplace, resale,\nand product-safety teams check product catalogs and listings against\nnormalized U.S. recall data. The API normalizes recall records from FDA\nenforcement reports, USDA FSIS recall/public-health-alert feeds, and CPSC\nconsumer product recalls.\n\nThis API is not affiliated with FDA, USDA, or CPSC and does not provide legal,\nmedical, or safety advice. Always use official agency notices for final decisions.\n" }, "paths": { "/v1/recalls/search": { "get": { "summary": "Search Recalls", "operationId": "recall_watch_search", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300, "title": "Q", "nullable": true } }, { "name": "source", "in": "query", "required": false, "schema": { "enum": [ "fda_food", "fda_drug", "fda_device", "usda_fsis", "cpsc" ], "type": "string", "title": "Source", "nullable": true } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80, "title": "Category", "nullable": true } }, { "name": "company", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 220, "title": "Company", "nullable": true } }, { "name": "brand", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 180, "title": "Brand", "nullable": true } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2, "title": "State", "nullable": true } }, { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date From", "nullable": true } }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "title": "Date To", "nullable": true } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 800, "title": "Cursor", "nullable": true } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallSearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Search normalized recall records by keyword and filters including source,\ncategory, company, state, and date range." } }, "/v1/recalls/{source}/{source_id}": { "get": { "summary": "Get Recall Detail", "operationId": "recall_watch_detail", "parameters": [ { "name": "source", "in": "path", "required": true, "schema": { "enum": [ "fda_food", "fda_drug", "fda_device", "usda_fsis", "cpsc" ], "type": "string", "title": "Source" } }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Source Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallDetailResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Fetch a single normalized recall record by source and source-specific ID." } }, "/v1/recalls/check": { "post": { "summary": "Check Product", "operationId": "recall_watch_check", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallCheckRequest" }, "example": { "title": "Mini blender 380ml", "brand": "Example", "company": "Example Inc", "identifiers": [ { "type": "upc", "value": "123456789012" } ], "limit": 10, "include_possible": true } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallCheckResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "description": "Match a product payload (title, brand, company, identifiers) against\nnormalized recall records and return matched/possible-match outcomes." } }, "/v1/recalls/source-status": { "get": { "summary": "Get Source Status", "operationId": "recall_watch_source_status", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallSourceStatusResponse" } } } } }, "description": "Return source freshness, sync status, and indexed record counts." } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "RecallCheckRequest": { "properties": { "title": { "type": "string", "maxLength": 300, "title": "Title", "nullable": true }, "brand": { "type": "string", "maxLength": 180, "title": "Brand", "nullable": true }, "company": { "type": "string", "maxLength": 220, "title": "Company", "nullable": true }, "description": { "type": "string", "maxLength": 2000, "title": "Description", "nullable": true }, "identifiers": { "items": { "$ref": "#/components/schemas/RecallIdentifier" }, "type": "array", "maxItems": 40, "title": "Identifiers" }, "limit": { "type": "integer", "maximum": 50.0, "minimum": 1.0, "title": "Limit", "default": 10 }, "include_possible": { "type": "boolean", "title": "Include Possible", "default": true } }, "additionalProperties": false, "type": "object", "title": "RecallCheckRequest" }, "RecallCheckResponse": { "properties": { "status": { "type": "string", "enum": [ "matched", "possible_match", "no_match" ], "title": "Status" }, "matches": { "items": { "$ref": "#/components/schemas/RecallMatch" }, "type": "array", "title": "Matches" }, "possible_matches": { "items": { "$ref": "#/components/schemas/RecallMatch" }, "type": "array", "title": "Possible Matches" }, "meta": { "$ref": "#/components/schemas/RecallMeta" } }, "type": "object", "required": [ "status", "meta" ], "title": "RecallCheckResponse" }, "RecallDetailResponse": { "properties": { "record": { "$ref": "#/components/schemas/RecallRecord" }, "meta": { "$ref": "#/components/schemas/RecallMeta" } }, "type": "object", "required": [ "record", "meta" ], "title": "RecallDetailResponse" }, "RecallIdentifier": { "properties": { "type": { "type": "string", "enum": [ "upc", "gtin", "asin", "model", "lot", "sku", "ndc", "ref", "other" ], "title": "Type" }, "value": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Value" } }, "type": "object", "required": [ "type", "value" ], "title": "RecallIdentifier" }, "RecallMatch": { "properties": { "match_type": { "type": "string", "maxLength": 40, "minLength": 1, "title": "Match Type" }, "score": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Score" }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "title": "Confidence" }, "evidence": { "$ref": "#/components/schemas/RecallMatchEvidence" }, "record": { "$ref": "#/components/schemas/RecallRecord" } }, "type": "object", "required": [ "match_type", "score", "confidence", "evidence", "record" ], "title": "RecallMatch" }, "RecallMatchEvidence": { "properties": { "matched_identifiers": { "items": { "$ref": "#/components/schemas/RecallIdentifier" }, "type": "array", "title": "Matched Identifiers" }, "matched_terms": { "items": { "type": "string" }, "type": "array", "title": "Matched Terms" } }, "type": "object", "title": "RecallMatchEvidence" }, "RecallMeta": { "properties": { "request_id": { "type": "string", "maxLength": 64, "minLength": 10, "title": "Request Id" }, "cached": { "type": "boolean", "title": "Cached", "default": false }, "schema_version": { "type": "string", "maxLength": 40, "minLength": 1, "title": "Schema Version" }, "stale": { "type": "boolean", "title": "Stale", "default": false } }, "type": "object", "required": [ "request_id", "schema_version" ], "title": "RecallMeta" }, "RecallRecord": { "properties": { "source": { "type": "string", "enum": [ "fda_food", "fda_drug", "fda_device", "usda_fsis", "cpsc" ], "title": "Source" }, "source_id": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Source Id" }, "category": { "type": "string", "maxLength": 80, "title": "Category", "default": "" }, "title": { "type": "string", "maxLength": 400, "title": "Title", "default": "" }, "description": { "type": "string", "maxLength": 4000, "title": "Description", "default": "" }, "company": { "type": "string", "maxLength": 300, "title": "Company", "default": "" }, "brands": { "items": { "type": "string" }, "type": "array", "title": "Brands" }, "products": { "items": { "type": "string" }, "type": "array", "title": "Products" }, "identifiers": { "items": { "$ref": "#/components/schemas/RecallIdentifier" }, "type": "array", "title": "Identifiers" }, "distribution_states": { "items": { "type": "string" }, "type": "array", "title": "Distribution States" }, "hazard": { "type": "string", "maxLength": 4000, "title": "Hazard", "default": "" }, "remedy": { "type": "string", "maxLength": 2000, "title": "Remedy", "default": "" }, "status": { "type": "string", "maxLength": 60, "title": "Status", "default": "" }, "classification": { "type": "string", "maxLength": 60, "title": "Classification", "default": "" }, "recall_date": { "type": "string", "format": "date", "title": "Recall Date", "nullable": true }, "last_updated": { "type": "string", "format": "date-time", "title": "Last Updated", "nullable": true }, "source_url": { "type": "string", "maxLength": 2083, "title": "Source Url", "default": "" } }, "type": "object", "required": [ "source", "source_id" ], "title": "RecallRecord" }, "RecallSearchResponse": { "properties": { "records": { "items": { "$ref": "#/components/schemas/RecallRecord" }, "type": "array", "title": "Records" }, "next_cursor": { "type": "string", "title": "Next Cursor", "nullable": true }, "meta": { "$ref": "#/components/schemas/RecallMeta" } }, "type": "object", "required": [ "records", "meta" ], "title": "RecallSearchResponse" }, "RecallSourceStatusItem": { "properties": { "source": { "type": "string", "enum": [ "fda_food", "fda_drug", "fda_device", "usda_fsis", "cpsc" ], "title": "Source" }, "status": { "type": "string", "maxLength": 40, "title": "Status", "default": "unknown" }, "last_started_at": { "type": "string", "format": "date-time", "title": "Last Started At", "nullable": true }, "last_completed_at": { "type": "string", "format": "date-time", "title": "Last Completed At", "nullable": true }, "last_success_at": { "type": "string", "format": "date-time", "title": "Last Success At", "nullable": true }, "last_error": { "type": "string", "maxLength": 500, "title": "Last Error", "default": "" }, "records_seen": { "type": "integer", "minimum": 0.0, "title": "Records Seen", "default": 0 }, "records_upserted": { "type": "integer", "minimum": 0.0, "title": "Records Upserted", "default": 0 }, "record_count": { "type": "integer", "minimum": 0.0, "title": "Record Count", "default": 0 }, "source_last_updated": { "type": "string", "format": "date-time", "title": "Source Last Updated", "nullable": true } }, "type": "object", "required": [ "source" ], "title": "RecallSourceStatusItem" }, "RecallSourceStatusResponse": { "properties": { "sources": { "items": { "$ref": "#/components/schemas/RecallSourceStatusItem" }, "type": "array", "title": "Sources" }, "meta": { "$ref": "#/components/schemas/RecallMeta" } }, "type": "object", "required": [ "sources", "meta" ], "title": "RecallSourceStatusResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "x-category": "Data", "x-documentation": { "readme": "# Product Recall Check API\n\n## What This API Does\n\nProduct Recall Check API is a normalized recall search and product-checking API for\nU.S. product safety data. It helps applications search recall records and check\nproduct listings, catalog items, SKUs, UPCs, NDCs, model numbers, lots, brands,\nand companies against indexed recall data.\n\nThe API aggregates and normalizes public recall data from:\n\n| Source | `source` value | Coverage in this API |\n| --- | --- | --- |\n| FDA food enforcement reports | `fda_food` | Food, beverage, supplement, and related FDA food enforcement records |\n| FDA drug enforcement reports | `fda_drug` | Drug recall enforcement records, including NDCs when available |\n| FDA medical device enforcement reports | `fda_device` | Device recall enforcement records, including model/ref identifiers when available |\n| USDA FSIS recalls and public-health alerts | `usda_fsis` | Meat, poultry, egg-product recalls and public-health alerts |\n| CPSC consumer product recalls | `cpsc` | Consumer product recalls such as appliances, toys, fixtures, batteries, and household goods |\n\nThis API is designed for product safety checks in e-commerce, marketplaces,\ncatalog enrichment, compliance tools, inventory workflows, resale platforms,\nretail operations, and internal risk dashboards.\n\n## Selling Point\n\nGovernment recall portals and public APIs are useful, but each agency has its\nown search interface, schema, field names, source identifiers, update behavior,\nand data quirks. Product Recall Check API provides a single integration layer over\nmultiple agencies.\n\nThe main value is not simply \"FDA data in an API.\" The value is:\n\n- **Unified multi-agency recall search** across FDA food, FDA drugs, FDA devices,\n USDA FSIS, and CPSC.\n- **One normalized response schema** for very different upstream sources.\n- **Product-to-recall matching** via `POST /v1/recalls/check`, so your app can\n ask \"does this product look recalled?\" instead of manually building agency\n search logic.\n- **Evidence-based match output** showing matched identifiers and matched terms.\n- **Source freshness visibility** via `GET /v1/recalls/source-status`.\n- **Developer-friendly pagination, filtering, and source IDs** for production\n integrations.\n\nUse this API when you want recall data inside a product workflow rather than a\nhuman manually searching agency websites.\n\n## Important Disclaimer\n\nThis API is not affiliated with FDA, USDA, FSIS, CPSC, or any other government\nagency. It does not provide legal, medical, safety, regulatory, or compliance\nadvice.\n\nRecall data is normalized from public source data. Always review the official\nsource notice before taking operational action such as removing a product,\ncontacting customers, issuing refunds, reporting compliance findings, or making\nsafety claims.\n\n## Authentication\n\nWhen calling through RapidAPI, send your RapidAPI headers:\n\n```bash\nX-RapidAPI-Key: \nX-RapidAPI-Host: \n```\n\nAll product endpoints are under:\n\n```text\n/v1/recalls\n```\n\n## Endpoint Summary\n\n| Endpoint | Method | Purpose |\n| --- | --- | --- |\n| `/v1/recalls/search` | `GET` | Search normalized recall records by keyword and filters |\n| `/v1/recalls/{source}/{source_id}` | `GET` | Fetch one recall record by source and source-specific ID |\n| `/v1/recalls/check` | `POST` | Check a product payload against recall records |\n| `/v1/recalls/source-status` | `GET` | View source freshness, sync state, and indexed record counts |\n\n## Core Concepts\n\n### `source`\n\n`source` tells you which upstream dataset the normalized record came from.\nValid values are:\n\n```text\nfda_food\nfda_drug\nfda_device\nusda_fsis\ncpsc\n```\n\nUse `source` together with `source_id` to fetch a stable detail record:\n\n```text\nGET /v1/recalls/{source}/{source_id}\n```\n\n### `source_id`\n\n`source_id` is the source-specific recall identifier. Examples:\n\n- FDA food: `H-0761-2026`\n- FDA drug: `D-0514-2026`\n- FDA device: `Z-2067-2026`\n- USDA FSIS: `PHA-05092026-01`\n- CPSC: `26479`\n\n### `identifiers`\n\nIdentifiers are structured product codes extracted from source data or supplied\nin check requests.\n\nSupported identifier types:\n\n```text\nupc\ngtin\nasin\nmodel\nlot\nsku\nndc\nref\nother\n```\n\nIdentifier coverage depends on what the source agency publishes. Exact\nidentifier matches are treated as stronger evidence than text overlap.\n\n### `meta`\n\nMost responses include:\n\n| Field | Meaning |\n| --- | --- |\n| `request_id` | Request identifier useful for support/debugging |\n| `cached` | Whether this response came from the API cache |\n| `schema_version` | Response schema version |\n| `stale` | Whether indexed source data is older than the configured sync interval |\n\n## Search Recalls\n\n```text\nGET /v1/recalls/search\n```\n\nUse search when you need to list recall records by keyword, source, company,\nstate, category, or date range.\n\n### Query Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `q` | string | Keyword query over normalized text fields |\n| `source` | enum | Optional source filter: `fda_food`, `fda_drug`, `fda_device`, `usda_fsis`, `cpsc` |\n| `category` | string | Optional normalized category filter |\n| `company` | string | Optional recalling firm/company filter |\n| `brand` | string | Optional brand filter where source data provides brands |\n| `state` | string | Optional 2-letter U.S. state filter for distribution states |\n| `date_from` | date | Optional lower recall-date bound, `YYYY-MM-DD` |\n| `date_to` | date | Optional upper recall-date bound, `YYYY-MM-DD` |\n| `limit` | integer | Page size. Use smaller limits for UI search and larger limits for backend sync/search workflows |\n| `cursor` | string | Pagination cursor returned as `next_cursor` from a prior response |\n\n### Example: Search FDA Drug Recalls\n\n```bash\ncurl -G \"https:///v1/recalls/search\" \\\n -H \"X-RapidAPI-Key: \" \\\n -H \"X-RapidAPI-Host: \" \\\n --data-urlencode \"source=fda_drug\" \\\n --data-urlencode \"q=duloxetine\" \\\n --data-urlencode \"company=Ajanta\" \\\n --data-urlencode \"limit=5\"\n```\n\n### Example: Search USDA FSIS Records Distributed In Illinois\n\n```bash\ncurl -G \"https:///v1/recalls/search\" \\\n -H \"X-RapidAPI-Key: \" \\\n -H \"X-RapidAPI-Host: \" \\\n --data-urlencode \"source=usda_fsis\" \\\n --data-urlencode \"state=IL\" \\\n --data-urlencode \"limit=10\"\n```\n\n### Search Response Shape\n\n```json\n{\n \"records\": [\n {\n \"source\": \"fda_drug\",\n \"source_id\": \"D-0514-2026\",\n \"category\": \"drugs\",\n \"title\": \"Duloxetine Delayed-Release Capsules, 30 mg...\",\n \"description\": \"Duloxetine Delayed-Release Capsules, 30 mg...\",\n \"company\": \"Ajanta Pharma Ltd.\",\n \"brands\": [],\n \"products\": [\"Duloxetine Delayed-Release Capsules, 30 mg...\"],\n \"identifiers\": [\n {\"type\": \"ndc\", \"value\": \"27241-098-09\"}\n ],\n \"distribution_states\": [],\n \"hazard\": \"CGMP Deviations...\",\n \"remedy\": \"\",\n \"status\": \"Ongoing\",\n \"classification\": \"Class II\",\n \"recall_date\": \"2026-04-29\",\n \"last_updated\": \"2026-05-04T00:00:00Z\",\n \"source_url\": \"https://www.accessdata.fda.gov/scripts/ires/?event=98785\"\n }\n ],\n \"next_cursor\": \"eyJyZWNhbGxfZGF0ZSI6...\",\n \"meta\": {\n \"request_id\": \"req_...\",\n \"cached\": false,\n \"schema_version\": \"1.0.0\",\n \"stale\": false\n }\n}\n```\n\n### Pagination\n\nIf `next_cursor` is not `null`, pass it back as `cursor` to fetch the next page:\n\n```bash\ncurl -G \"https:///v1/recalls/search\" \\\n -H \"X-RapidAPI-Key: \" \\\n -H \"X-RapidAPI-Host: \" \\\n --data-urlencode \"source=fda_drug\" \\\n --data-urlencode \"limit=5\" \\\n --data-urlencode \"cursor=\"\n```\n\nInvalid cursors return a `422` error with code `invalid_cursor`.\n\n## Get Recall Detail\n\n```text\nGET /v1/recalls/{source}/{source_id}\n```\n\nUse detail lookup after a search result or match result when your app needs the\nfull normalized recall record.\n\n### Example\n\n```bash\ncurl \"https:///v1/recalls/fda_drug/D-0514-2026\" \\\n -H \"X-RapidAPI-Key: \" \\\n -H \"X-RapidAPI-Host: \"\n```\n\n### Detail Response Shape\n\n```json\n{\n \"record\": {\n \"source\": \"fda_drug\",\n \"source_id\": \"D-0514-2026\",\n \"category\": \"drugs\",\n \"title\": \"Duloxetine Delayed-Release Capsules, 30 mg...\",\n \"company\": \"Ajanta Pharma Ltd.\",\n \"identifiers\": [\n {\"type\": \"ndc\", \"value\": \"27241-098-09\"}\n ],\n \"hazard\": \"CGMP Deviations...\",\n \"recall_date\": \"2026-04-29\",\n \"source_url\": \"https://www.accessdata.fda.gov/scripts/ires/?event=98785\"\n },\n \"meta\": {\n \"request_id\": \"req_...\",\n \"cached\": false,\n \"schema_version\": \"1.0.0\",\n \"stale\": false\n }\n}\n```\n\nIf no record exists for the supplied source and source ID, the API returns `404`\nwith error code `recall_not_found`.\n\n## Check A Product Against Recall Data\n\n```text\nPOST /v1/recalls/check\n```\n\nUse this endpoint when you have a product/listing/catalog item and want to know\nwhether it looks like a known recall record.\n\nThis endpoint is the main workflow endpoint. It compares the supplied product\ncontext against normalized recall records and returns:\n\n- strong matches in `matches`\n- weaker but relevant candidates in `possible_matches`\n- match evidence, including matched identifiers and matched text terms\n\n### Request Body Fields\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `title` | string | No | Product title or listing title |\n| `brand` | string | No | Brand name if known |\n| `company` | string | No | Manufacturer, recalling firm, seller, or company name |\n| `description` | string | No | Product description or listing text |\n| `identifiers` | array | No | Product identifiers such as UPC, GTIN, NDC, model, lot, SKU, ASIN |\n| `limit` | integer | No | Maximum matches to return. Default is `10`; maximum is `50` |\n| `include_possible` | boolean | No | Whether to include lower-confidence possible matches. Default is `true` |\n\nThe request rejects unknown extra fields. Keep your payload focused on known\nproduct attributes.\n\n### Identifier Object\n\n```json\n{\n \"type\": \"ndc\",\n \"value\": \"27241-098-09\"\n}\n```\n\nSupported `type` values:\n\n```text\nupc, gtin, asin, model, lot, sku, ndc, ref, other\n```\n\n### Example: Check By NDC\n\n```bash\ncurl \"https:///v1/recalls/check\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-RapidAPI-Key: \" \\\n -H \"X-RapidAPI-Host: \" \\\n -d '{\n \"title\": \"Duloxetine Delayed-Release Capsules 30 mg\",\n \"company\": \"Ajanta Pharma Ltd.\",\n \"identifiers\": [\n {\"type\": \"ndc\", \"value\": \"27241-098-09\"}\n ],\n \"limit\": 5,\n \"include_possible\": true\n }'\n```\n\n### Example: Check By Product Title And Company\n\n```bash\ncurl \"https:///v1/recalls/check\" \\\n -H \"Content-Type: application/json\" \\\n -H \"X-RapidAPI-Key: \" \\\n -H \"X-RapidAPI-Host: \" \\\n -d '{\n \"title\": \"Minka Bardon Series Pendant Light Fixtures\",\n \"company\": \"Minka Lighting Group\",\n \"limit\": 3,\n \"include_possible\": true\n }'\n```\n\n### Check Response Shape\n\n```json\n{\n \"status\": \"matched\",\n \"matches\": [\n {\n \"match_type\": \"identifier_exact\",\n \"score\": 0.98,\n \"confidence\": \"high\",\n \"evidence\": {\n \"matched_identifiers\": [\n {\"type\": \"ndc\", \"value\": \"27241-098-09\"}\n ],\n \"matched_terms\": []\n },\n \"record\": {\n \"source\": \"fda_drug\",\n \"source_id\": \"D-0514-2026\",\n \"title\": \"Duloxetine Delayed-Release Capsules, 30 mg...\",\n \"company\": \"Ajanta Pharma Ltd.\",\n \"recall_date\": \"2026-04-29\",\n \"source_url\": \"https://www.accessdata.fda.gov/scripts/ires/?event=98785\"\n }\n }\n ],\n \"possible_matches\": [],\n \"meta\": {\n \"request_id\": \"req_...\",\n \"cached\": false,\n \"schema_version\": \"1.0.0\",\n \"stale\": false\n }\n}\n```\n\n### How To Interpret Match Results\n\n| Field | Meaning |\n| --- | --- |\n| `status` | Overall outcome: `matched`, `possible_match`, or `no_match` |\n| `matches` | Strong matches, usually exact identifier matches or high-confidence evidence |\n| `possible_matches` | Lower-confidence candidates that may need human review |\n| `match_type` | Why the record matched, for example `identifier_exact` or `title_or_brand_overlap` |\n| `score` | Numeric score from `0.0` to `1.0`; higher means stronger match evidence |\n| `confidence` | Human-friendly confidence bucket: `high`, `medium`, or `low` |\n| `evidence.matched_identifiers` | Exact identifier values that matched |\n| `evidence.matched_terms` | Text terms shared between the input and the recall record |\n| `record` | The normalized recall record that matched |\n\nRecommended handling:\n\n- Treat `matched` with `confidence=high` as a strong signal for review.\n- Treat `possible_match` as a candidate requiring human review.\n- Treat `no_match` as \"no qualifying match found in the current index\", not a\n guarantee that the product has never been recalled.\n\n## Source Status\n\n```text\nGET /v1/recalls/source-status\n```\n\nUse this endpoint to monitor data freshness and source ingestion health.\n\n### Example\n\n```bash\ncurl \"https:///v1/recalls/source-status\" \\\n -H \"X-RapidAPI-Key: \" \\\n -H \"X-RapidAPI-Host: \"\n```\n\n### Source Status Response Shape\n\n```json\n{\n \"sources\": [\n {\n \"source\": \"fda_food\",\n \"status\": \"ok\",\n \"last_started_at\": \"2026-05-20T10:13:31.770233Z\",\n \"last_completed_at\": \"2026-05-20T10:13:33.537046Z\",\n \"last_success_at\": \"2026-05-20T10:13:33.537046Z\",\n \"last_error\": \"\",\n \"records_seen\": 105,\n \"records_upserted\": 104,\n \"record_count\": 104,\n \"source_last_updated\": \"2026-05-13T00:00:00Z\"\n }\n ],\n \"meta\": {\n \"request_id\": \"req_...\",\n \"cached\": false,\n \"schema_version\": \"1.0.0\",\n \"stale\": false\n }\n}\n```\n\n### Source Status Fields\n\n| Field | Meaning |\n| --- | --- |\n| `status` | Current source state, such as `ok`, `degraded`, `failed`, `running`, or `unknown` |\n| `last_started_at` | Most recent sync start time |\n| `last_completed_at` | Most recent sync completion time |\n| `last_success_at` | Most recent successful sync time |\n| `last_error` | Last source/sync error, if any |\n| `records_seen` | Records seen in the most recent sync |\n| `records_upserted` | Records inserted or updated in the most recent sync |\n| `record_count` | Current indexed records for that source |\n| `source_last_updated` | Source-reported last-updated timestamp when available |\n\nIf `meta.stale` is `true`, the current index is older than the configured sync\ninterval. Your application can still use the data, but should treat freshness as\ndegraded.\n\n## Normalized Recall Record Fields\n\nEvery search, detail, and match response uses the same recall record shape:\n\n| Field | Description |\n| --- | --- |\n| `source` | Source dataset enum |\n| `source_id` | Source-specific recall ID |\n| `category` | Normalized product category when available |\n| `title` | Human-readable recall title or product summary |\n| `description` | Product/recall description |\n| `company` | Recalling firm, establishment, manufacturer, importer, distributor, or similar source-provided company |\n| `brands` | Brand names when source data provides them |\n| `products` | Affected product descriptions |\n| `identifiers` | Structured UPC, GTIN, NDC, model, lot, SKU, ASIN, ref, or other identifiers |\n| `distribution_states` | U.S. state codes when source data provides distribution information |\n| `hazard` | Source-provided recall reason, hazard, or contamination/mislabeling issue |\n| `remedy` | Source-provided consumer remedy when available |\n| `status` | Source-provided recall status when available |\n| `classification` | Source classification such as FDA class or FSIS alert/classification |\n| `recall_date` | Recall initiation or publication date |\n| `last_updated` | Best available source/update date |\n| `source_url` | URL to source detail or official record when available |\n\nFields may be empty when the upstream source does not provide that value.\n\n## Matching Notes\n\nMatching is deterministic and evidence-based. The API does not use vague\ngenerative matching for final results. Exact identifiers such as UPC, GTIN, NDC,\nmodel, lot, ref, SKU, and ASIN are stronger evidence than text overlap. Text\nmatching uses product title, description, brand, company, products, and hazard\nterms.\n\nFalse positives and false negatives are still possible because:\n\n- Agency records may omit UPCs, NDCs, models, lot numbers, brands, or states.\n- Product listings may use seller-written titles that differ from official\n recall language.\n- A recall can apply to only specific lots, dates, packaging sizes, or regions.\n- Source agencies may update records after initial publication.\n\nFor high-risk workflows, use the API as a screening and monitoring layer, then\nreview the official `source_url` record before action.\n\n## Error Handling\n\nTypical API errors:\n\n| HTTP status | Example code | Meaning |\n| --- | --- | --- |\n| `400` or `422` | validation errors | Query or body fields are invalid |\n| `422` | `invalid_cursor` | Pagination cursor is malformed or expired |\n| `404` | `recall_not_found` | No detail record exists for the supplied source and source ID |\n| `413` | `payload_too_large` | Request body exceeds configured product limit |\n| `401` or `403` | auth errors | RapidAPI authentication/proxy validation failed |\n\n## Common Integration Patterns\n\n### Product Listing Safety Check\n\n1. Send product title, company, brand, and identifiers to `/v1/recalls/check`.\n2. If `status=matched`, flag the product for review.\n3. If `status=possible_match`, show candidate recall records to an operator.\n4. If `status=no_match`, continue normal workflow while keeping periodic checks.\n\n### Catalog Monitoring\n\n1. Periodically check high-risk catalog items by UPC, NDC, model, lot, or brand.\n2. Store returned `source` and `source_id`.\n3. Use `/v1/recalls/{source}/{source_id}` to refresh details as needed.\n4. Monitor `/v1/recalls/source-status` for freshness.\n\n### Recall Search UI\n\n1. Use `/v1/recalls/search` with `q`, `source`, `company`, `state`, and date filters.\n2. Display `title`, `company`, `hazard`, `recall_date`, `classification`, and `source`.\n3. Use `next_cursor` for pagination.\n4. Link users to the official `source_url`.\n\n## Best Practices\n\n- Provide identifiers whenever possible. Exact identifiers produce stronger\n results than text-only matching.\n- Include both product title and company/brand for better text matching.\n- Use `include_possible=true` for review workflows and `include_possible=false`\n when you only want higher-confidence outputs.\n- Store `source` and `source_id` rather than trying to parse source URLs.\n- Monitor `meta.stale` and `/source-status` if freshness matters to your use case.\n- Always review official source records before operational or safety decisions.\n" } }