Provider Alerts API¶

Complete API reference for managing provider tracking and retrieving alerts for CMS Provider Specific File (IPSF and OPSF) structural updates.

Overview¶

The Provider Alerts API allows users to track specific CMS Certification Numbers (CCNs). When structural changes occur (like a new record version or a material change to payment-related fields), the system automatically generates alerts. You can then query, filter, export, and manage these alerts.

Base Path: /api/v1/provider-alerts

Authentication: Required for all endpoints (Bearer token). Alerts and tracking lists are isolated by your organization (org_id).

Tracking Endpoints¶

Get Tracked Providers¶

Retrieve the list of all provider CCNs currently tracked by your organization.

Endpoint: GET /provider-alerts/trackers

Response:

{
  "items": [
    {
      "id": 1,
      "provider_ccn": "010001",
      "last_checked": "2024-03-05T12:00:00Z",
      "created_at": "2024-03-01T08:30:00Z"
    }
  ],
  "count": 1,
  "limit": 250
}

Add Tracked Providers¶

Add one or more provider CCNs to your organization's tracking list. There is a maximum limit of 250 tracked CCNs per organization.

Endpoint: POST /provider-alerts/trackers

Request Body:

{
  "provider_ccns": ["010001", "123456"]
}

Response: Returns the updated list of tracked providers (same structure as GET /provider-alerts/trackers).

Remove Tracked Provider¶

Remove a specific provider CCN from your tracking list.

Endpoint: DELETE /provider-alerts/trackers/{ccn}

Path Parameters:

Response:

{
  "status": "success"
}

Alerts Endpoints¶

Get Alerts Feed¶

Retrieve a paginated feed of alerts generated for your tracked providers.

Endpoint: GET /provider-alerts/

Query Parameters:

Response:

{
  "items": [
    {
      "id": 105,
      "provider_ccn": "010001",
      "table_name": "ipsf",
      "effective_date": 20240101,
      "field_name": "wage_index_location",
      "old_value": "1.000",
      "new_value": "1.050",
      "is_seen": false,
      "patch_timestamp": "2024-03-05T12:00:00Z",
      "created_at": "2024-03-05T12:00:10Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}

Download Alerts (CSV)¶

Export provider alerts as a CSV file. Accepts the same filters as the feed endpoint.

Endpoint: GET /provider-alerts/download

Query Parameters:

Response: Returns a standard CSV file attachment (e.g., provider_alerts_20240305_120000.csv) with limits capped safely at 20,000 records.

Get Unread Count¶

Get a fast count of unseen alerts, typically used for dashboard notification badges.

Endpoint: GET /provider-alerts/unread-count

Response:

{
  "count": 12
}

Mark All Alerts as Seen¶

Bulk update all unseen alerts as seen for your organization.

Endpoint: POST /provider-alerts/mark-seen

Response:

{
  "status": "success"
}

Mark Individual Alert as Seen¶

Update a specific alert's status to seen.

Endpoint: POST /provider-alerts/mark-seen/{alert_id}

Path Parameters:

Response:

{
  "status": "success"
}

Error Handling¶