Provider Master API¶

Access and manage the master provider database, which aggregates data from multiple CMS sources.

Overview¶

The Provider Master API provides a unified view of provider data, combining information from various CMS datasets (Hospital, ASC, Hospice, HHA, etc.). It supports searching, detailed lookups with fallback logic, and administrative management of the data.

Base Path: /api/v1/provider-master

Authentication: Required for all endpoints (Bearer token). Some endpoints require superuser privileges.

User Endpoints¶

Search Providers¶

Search the provider master database with various filters.

Endpoint: GET /provider-master/search

Query Parameters:

Parameter	Type	Required	Description
`provider_num`	string	No	Provider number (CCN)
`facility_name`	string	No	Facility name (partial match supported)
`state`	string	No	State code (e.g., 'CA')
`city`	string	No	City name (partial match supported)
`provider_category`	string	No	Provider category code
`skip`	integer	No	Number of records to skip (default: 0)
`limit`	integer	No	Maximum records to return (default: 50, max: 500)

Response:

{
  "data": [
    {
      "id": 1,
      "prvdr_num": "010001",
      "fac_name": "SOUTHEAST HEALTH MEDICAL CENTER",
      "state_cd": "AL",
      "city_name": "DOTHAN",
      "provider_type": "Hospital"
    }
  ],
  "count": 100
}

Lookup Provider Details¶

Lookup provider details with intelligent fallback logic.

Endpoint: GET /provider-master/lookup-details

Query Parameters:

Parameter	Type	Required	Description
`alternate_id`	string	No	Alternate ID (CCN) to lookup first
`npi`	string	No	NPI to use as fallback if alternate_id fails

Logic: 1. Attempts to find provider by alternate_id (CCN) in the master table. 2. If not found and npi is provided: * Searches IPSF for the NPI to get a CCN. * If not in IPSF, searches OPSF for the NPI to get a CCN. * If a CCN is found, looks up the provider in the master table using that CCN.

Response:

{
  "facility_name": "SOUTHEAST HEALTH MEDICAL CENTER",
  "city": "DOTHAN",
  "state": "AL",
  "street_address": "1108 ROSS CLARK CIRCLE",
  "zip_code": "36301",
  "phone": "3347938701",
  "provider_type": "Hospital",
  "found": true,
  "lookup_method": "alternate_id"
}

Get Provider Statistics¶

Get statistics about the provider master data.

Endpoint: GET /provider-master/stats

Response:

{
  "total_providers": 15000,
  "top_states": [
    { "state": "CA", "count": 1200 },
    { "state": "TX", "count": 1100 }
  ],
  "last_updated": "2024-01-15T10:00:00Z"
}

Get Provider by Number¶

Retrieve a specific provider by their provider number (CCN).

Endpoint: GET /provider-master/{provider_num}

Path Parameters:

Parameter	Type	Required	Description
`provider_num`	string	Yes	Provider number (CCN)

Response:

Returns the full provider master record.

Admin Endpoints¶

[!WARNING] These endpoints require superuser/admin privileges.

Get Update Status¶

Get the current status of the provider master update process.

Endpoint: GET /provider-master/status

Response:

{
  "status": "IDLE",
  "table": "provider_master",
  "last_run": "2024-01-15T10:00:00Z",
  "is_running": false
}

Trigger Update¶

Trigger a full update of the provider master data from CMS sources. This runs as a background task.

Endpoint: POST /provider-master/update

Response:

{
  "message": "Provider master update process started for all datasets",
  "status": "processing"
}

Debug Dataset Info¶

Test dataset information extraction from the CMS API.

Endpoint: GET /provider-master/debug/test-dataset-info

Response:

Returns raw dataset information and download URLs for debugging purposes.