API Documentation

Technical reference for the IsMyProductRecalled API.

Authentication

All API requests require an API key passed in the X-API-Key header.

curl -X POST https://ismyproductrecalled.com/api/v1/check/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: impr_your_api_key_here" \
  -d '{"items": [{"id": "1", "upc": "012345678901"}]}'

Rate Limits

Rate limits are enforced per API key. Headers are included in every response.

Tier	Per Minute	Per Day
Basic	60	2,000
Premium	200	25,000
Enterprise	1,000+	Custom

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

POST /api/v1/check/bulk

Check multiple products for recalls in a single request. Maximum 100 items.

Request Body

{
  "items": [
    {
      "id": "sku-001",           // Your reference ID (required)
      "upc": "012345678901"      // UPC/EAN barcode (optional)
    },
    {
      "id": "sku-002",
      "brand": "Acme",           // Brand name (optional)
      "product_name": "Widget"   // Product name (optional)
    }
  ],
  "include_terminated": false    // Include non-active recalls (optional)
}

Response

{
  "success": true,
  "data": {
    "total_items": 2,
    "items_with_recalls": 1,
    "items_without_recalls": 1,
    "results": [
      {
        "id": "sku-001",
        "has_recalls": true,
        "match_count": 1,
        "matches": [
          {
            "recall_id": "uuid",
            "source": "cpsc",
            "product_name": "Widget Model X",
            "brand": "Acme",
            "category": "electronics",
            "recall_date": "2024-01-15",
            "classification": "Class I",
            "source_url": "https://...",
            "confidence": 1.0,
            "match_type": "upc_exact"
          }
        ]
      },
      {
        "id": "sku-002",
        "has_recalls": false,
        "match_count": 0,
        "matches": []
      }
    ]
  }
}

Match Types

upc_exact - Exact UPC match (confidence: 1.0)
brand_product - Brand + product name match (confidence: 0.7-0.95)

POST /api/v1/check

Check a single product for recalls with detailed results.

Request Body

{
  "upc": "012345678901",         // UPC/EAN barcode
  "brand": "Acme",               // Brand name (optional)
  "product_name": "Widget",      // Product name (optional)
  "query": "acme widget",        // Text search (optional)
  "category": "electronics",     // Filter by category (optional)
  "source": "cpsc",              // Filter by source (optional)
  "include_terminated": false    // Include non-active recalls
}

GET /api/v1/recalls

Search and filter the recall database.

Response Fields

Each recall in the response includes:

{
  "id": "uuid",
  "source": "cpsc",
  "source_id": "12345",
  "source_url": "https://www.cpsc.gov/...",
  "product_name": "Widget Model X",
  "brand": "Acme",
  "category": "electronics",
  "recall_date": "2024-01-15",
  "classification": "Class I",
  "status": "active",
  "reason": "Product can overheat...",
  "hazard": "Fire hazard",
  "remedy": "Full refund",
  "lot_codes": ["LOT123", "LOT456"],
  "upc_codes": ["012345678901"],
  "distribution_states": null,
  "last_updated": "2024-01-16T10:00:00Z",
  "ai_severity_label": "High",
  "ai_severity_reasoning": "Fire hazard can...",
  "image_urls": [
    "https://www.cpsc.gov/s3fs-public/image1.jpg",
    "https://www.cpsc.gov/s3fs-public/image2.jpg"
  ]
}

Note: image_urls currently available for CPSC recalls only. Other sources may be added in the future.

Query Parameters

Parameter	Type	Description
`q`	string	Search query
`source`	string	fda, usda, cpsc, nhtsa
`category`	string	food, medication, baby, toys, etc.
`classification`	string	Class I, Class II, Class III
`start_date`	string	YYYY-MM-DD format
`end_date`	string	YYYY-MM-DD format
`page`	number	Page number (default: 1)
`limit`	number	Results per page (max: 100)

Webhooks

Get notified when new recalls match your criteria. Premium and Enterprise tiers only.

Setup

Contact us to configure your webhook URL and receive your webhook secret. We'll set up the categories and sources you want to monitor.

Payload

{
  "event": "new_recall",
  "timestamp": "2024-01-15T10:30:00Z",
  "recall": {
    "id": "uuid",
    "source": "cpsc",
    "product_name": "Widget Model X",
    "brand": "Acme",
    "category": "electronics",
    "recall_date": "2024-01-15",
    "classification": "Class I",
    "hazard": "Fire hazard",
    "remedy": "Full refund",
    "source_url": "https://...",
    "image_urls": ["https://www.cpsc.gov/..."]
  }
}

Signature Verification

All webhooks include an HMAC-SHA256 signature in the X-Webhook-Signature header. Verify this to ensure the request came from us.

// Node.js verification example
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Requirements

HTTPS endpoints only (HTTP not supported)
Must respond with 2xx status within 30 seconds
Failed deliveries retry up to 3 times

Error Handling

The API uses standard HTTP status codes.

Status	Description
200	Success
400	Bad request (invalid parameters)
401	Unauthorized (missing or invalid API key)
403	Forbidden (access restricted)
429	Rate limit exceeded
500	Server error

Error Response Format

{
  "success": false,
  "error": {
    "message": "API key required. Contact us for access.",
    "code": "UNAUTHORIZED"
  }
}

Data Coverage Note

UPC barcode matching is most reliable for CPSC consumer product recalls. FDA and USDA recalls may have limited UPC data. For best results, also include brand and product name when checking products.

Questions about integration?

Contact api@ismyproductrecalled.com