483 Watchlist & Monitoring

Monitor FDA-regulated facilities for new citations, classification changes, and risk score changes with automated alerts.

Tier Access

Required Tier: Starter+ (Starter, Pro, Enterprise)

Rate limits apply per tier — see Rate Limits for details.

POST /v1/483/watchlist

Add a facility to your watchlist for automated monitoring.

Request

POST https://api.ctwise.ai/v1/483/watchlist
X-Api-Key: YOUR_API_KEY
Content-Type: application/json

Request Body

{
  "fei_number": "3005012345",
  "legal_name": "Acme Pharmaceutical Manufacturing",
  "webhook_url": "https://api.yourcompany.com/webhooks/fda-alerts",
  "alert_on": ["new_citation", "classification_change", "risk_score_change"]
}

Parameters

Parameter	Type	Required	Description
fei_number	string	Yes	FDA Establishment Identifier
legal_name	string	No	Facility legal name for reference
webhook_url	string	No	HTTPS webhook URL for real-time alerts
alert_on	string[]	No	Alert types to monitor (defaults to all three)

Alert Types

Alert Type	Description
new_citation	New FDA 483 citation issued to facility
classification_change	Inspection classification changed (e.g., VAI to OAI)
risk_score_change	Facility risk score changed significantly

Response

Status: 201 Created

{
  "watchlist_id": "wl_5356aba919a14c25",
  "tenant_id": "default-tenant",
  "fei_number": "3005012345",
  "legal_name": "Acme Pharmaceutical Manufacturing",
  "webhook_url": "https://api.yourcompany.com/webhooks/fda-alerts",
  "alert_on": ["new_citation", "classification_change", "risk_score_change"],
  "created_at": "2026-02-23T18:30:00.123456+00:00"
}

Response Fields

Field	Type	Description
watchlist_id	string	Unique watchlist entry identifier (format: wl_<hex>)
tenant_id	string	Tenant that owns this watchlist entry
fei_number	string	FDA Establishment Identifier
legal_name	string	Facility legal name (or null if not provided)
webhook_url	string	Configured webhook URL (or null)
alert_on	string[]	Alert types configured for this entry
created_at	string	Entry creation timestamp (ISO 8601)

---

GET /v1/483/watchlist

Retrieve your current watchlist entries with pagination.

Request

GET https://api.ctwise.ai/v1/483/watchlist?limit=20&offset=0
X-Api-Key: YOUR_API_KEY

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum results to return (default: 20, max: 100)
offset	integer	No	Number of results to skip (default: 0)

Response

{
  "results": [
    {
      "watchlist_id": "wl_5356aba919a14c25",
      "fei_number": "3005012345",
      "legal_name": "Acme Pharmaceutical Manufacturing",
      "webhook_url": "https://api.yourcompany.com/webhooks/fda-alerts",
      "alert_on": ["new_citation", "classification_change", "risk_score_change"],
      "created_at": "2026-02-23T18:30:00.123456+00:00",
      "last_checked": null
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20,
  "query_metadata": {
    "execution_time_ms": 45
  }
}

Response Fields

Field	Type	Description
results	array	Array of watchlist entries
results[].watchlist_id	string	Unique entry identifier
results[].fei_number	string	FDA Establishment Identifier
results[].legal_name	string	Facility legal name
results[].webhook_url	string	Webhook URL (or null)
results[].alert_on	string[]	Alert types
results[].created_at	string	Creation timestamp
results[].last_checked	string	Last alert check timestamp (or null)
total	integer	Total entries for tenant
offset	integer	Current offset
limit	integer	Page size
query_metadata	object	Execution metadata

---

DELETE /v1/483/watchlist/{id}

Remove a watchlist entry and stop monitoring.

Request

DELETE https://api.ctwise.ai/v1/483/watchlist/wl_5356aba919a14c25
X-Api-Key: YOUR_API_KEY

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Watchlist entry ID to delete

Response

{
  "deleted": true,
  "watchlist_id": "wl_5356aba919a14c25"
}

---

Examples

Add Facility to Watchlist

curl -X POST "https://api.ctwise.ai/v1/483/watchlist" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fei_number": "3005012345",
    "legal_name": "Key Supplier - API Manufacturing",
    "webhook_url": "https://api.yourcompany.com/webhooks/fda",
    "alert_on": ["new_citation", "classification_change"]
  }'

Get Watchlist

curl -X GET "https://api.ctwise.ai/v1/483/watchlist" \
  -H "X-Api-Key: YOUR_API_KEY"

Delete Watchlist Entry

curl -X DELETE "https://api.ctwise.ai/v1/483/watchlist/wl_5356aba919a14c25" \
  -H "X-Api-Key: YOUR_API_KEY"

Python Example - Add and Monitor

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.ctwise.ai/v1"

# Add facility to watchlist
response = requests.post(
    f"{BASE_URL}/483/watchlist",
    headers={
        "X-Api-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "fei_number": "3005012345",
        "legal_name": "Primary API Supplier",
        "webhook_url": "https://api.yourcompany.com/webhooks/fda-alerts",
        "alert_on": ["new_citation", "classification_change", "risk_score_change"]
    }
)

entry = response.json()
print(f"Watchlist entry created: {entry['watchlist_id']}")
print(f"Monitoring FEI: {entry['fei_number']}")
print(f"Alerts: {', '.join(entry['alert_on'])}")

# List all watchlist entries
response = requests.get(
    f"{BASE_URL}/483/watchlist",
    headers={"X-Api-Key": API_KEY}
)

data = response.json()
print(f"\nMonitoring {data['total']} facilities:")
for item in data['results']:
    print(f"  {item['fei_number']} - {item['legal_name'] or 'No name'}")

JavaScript Example - CRUD Operations

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.ctwise.ai/v1';

// Add to watchlist
const createResponse = await fetch(`${BASE_URL}/483/watchlist`, {
  method: 'POST',
  headers: {
    'X-Api-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fei_number: '3005012345',
    legal_name: 'Critical Supplier',
    alert_on: ['new_citation', 'classification_change']
  })
});

const entry = await createResponse.json();
console.log(`Created: ${entry.watchlist_id}`);

// List watchlist
const listResponse = await fetch(`${BASE_URL}/483/watchlist`, {
  headers: { 'X-Api-Key': API_KEY }
});

const data = await listResponse.json();
console.log(`Monitoring ${data.total} facilities`);

// Delete entry
const deleteResponse = await fetch(
  `${BASE_URL}/483/watchlist/${entry.watchlist_id}`,
  {
    method: 'DELETE',
    headers: { 'X-Api-Key': API_KEY }
  }
);

const result = await deleteResponse.json();
console.log(`Deleted: ${result.deleted}`);

Error Responses

Missing FEI Number

{
  "error": "'fei_number' is required",
  "status_code": 400
}

Status: 400 Bad Request

Invalid Webhook URL

{
  "error": "'webhook_url' must be an HTTPS URL",
  "status_code": 400
}

Status: 400 Bad Request

Invalid Alert Types

{
  "error": "Invalid alert_on values: {'invalid_type'}. Valid: {'new_citation', 'classification_change', 'risk_score_change'}",
  "status_code": 400
}

Status: 400 Bad Request

Watchlist Entry Not Found

{
  "error": "Watchlist entry 'wl_nonexistent' not found",
  "status_code": 404
}

Status: 404 Not Found

Performance

Metric	Target
Create response time	< 2 seconds
List response time	< 2 seconds
Delete response time	< 2 seconds
Data storage	S3 JSONL (durable, versioned)
Timeout	30 seconds

Best Practices

1. One entry per facility - Each POST creates a single watchlist entry for one FEI number
2. Webhook reliability - Ensure your webhook endpoint returns 200 OK within 5 seconds
3. Alert selection - Be selective with alert_on types to reduce noise
4. Periodic review - Periodically review and clean up your watchlist as supplier relationships change

---

Related Endpoints

• GET /v1/483/facilities - Facility details
• POST /v1/483/observations/search - Search observations
• GET /v1/483/citations/trending - Trending citations