API Reference

Integrate HealthPriceWatch with your systems

⚠️ API Access

The HealthPriceWatch API is currently available to Enterprise customers only. Contact sales@healthpricewatch.com to discuss API access for your organization.

Overview

The HealthPriceWatch API allows you to programmatically access compliance scan data, trigger on-demand scans, and integrate compliance monitoring into your existing workflows and systems.

Base URL

https://api.healthpricewatch.com/v1

Authentication

All API requests require authentication using an API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate API keys in your account settings under "API Access"

Rate Limits

Standard tier: 100 requests/hour
Enterprise tier: 1,000 requests/hour
Rate limit headers included in all responses

Endpoints

GET/scans

Retrieve compliance scan history for your hospital(s).

Query Parameters

Parameter	Type	Description
ccn	string	Filter by hospital CCN
from_date	ISO 8601	Start date for scan history
to_date	ISO 8601	End date for scan history
limit	integer	Max results (default: 50, max: 100)

Example Request

curl -X GET "https://api.healthpricewatch.com/v1/scans?ccn=050123&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "scans": [
    {
      "id": "scan_abc123",
      "hospital_ccn": "050123",
      "hospital_name": "Example Hospital",
      "score": 78,
      "violations_count": 6,
      "critical_count": 2,
      "high_count": 2,
      "medium_count": 2,
      "accumulated_liability": 490500.00,
      "scanned_at": "2025-10-07T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

GET/scans/:id

Retrieve detailed information about a specific scan.

Example Request

curl -X GET "https://api.healthpricewatch.com/v1/scans/scan_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "scan_abc123",
  "hospital_ccn": "050123",
  "hospital_name": "Example Hospital",
  "score": 78,
  "violations": [
    {
      "id": "viol_xyz789",
      "severity": "critical",
      "type": "missing_file",
      "description": "Standard charges file not accessible",
      "detected_at": "2025-10-07T10:00:00Z",
      "estimated_daily_penalty": 5500.00
    }
  ],
  "scanned_at": "2025-10-07T10:00:00Z"
}

POST/scans

Trigger an on-demand compliance scan for a hospital.

Request Body

{
  "hospital_ccn": "050123"
}

Example Request

curl -X POST "https://api.healthpricewatch.com/v1/scans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hospital_ccn": "050123"}'

Example Response

{
  "id": "scan_new456",
  "status": "pending",
  "hospital_ccn": "050123",
  "created_at": "2025-10-07T14:30:00Z",
  "estimated_completion": "2025-10-07T14:40:00Z"
}

Note: On-demand scans typically complete in 5-10 minutes

GET/hospitals

List all hospitals in your account.

Example Response

{
  "hospitals": [
    {
      "ccn": "050123",
      "name": "Example Hospital",
      "city": "San Francisco",
      "state": "CA",
      "latest_score": 78,
      "last_scanned_at": "2025-10-07T10:00:00Z"
    }
  ]
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "status": 401
  }
}

Common Error Codes

Code	Status	Description
unauthorized	401	Invalid or missing API key
forbidden	403	Insufficient permissions
not_found	404	Resource not found
rate_limit_exceeded	429	Too many requests
server_error	500	Internal server error

Webhooks

Configure webhooks to receive real-time notifications when scans complete or new violations are detected.

Event Types

scan.completed - Scan finished successfully
violation.detected - New violation found
violation.resolved - Violation no longer detected
score.changed - Compliance score changed significantly

Configure webhooks in your account settings or contact support for assistance.

Need API Access?

The API is available to Enterprise customers. Contact our sales team to discuss your integration requirements.

Contact Sales