Provider Tables API¶

Complete API reference for querying CMS Provider Specific File (IPSF and OPSF) data programmatically.

Overview¶

The Provider Tables API provides read-only access to CMS Inpatient Provider Specific File (IPSF) and Outpatient Provider Specific File (OPSF) data. These files contain provider-specific data used for Medicare payment calculations.

Base Path: /api/v1/provider-tables

Authentication: Required for all endpoints (Bearer token)

Table Types¶

The following table types are available:

Endpoints¶

Search Provider Tables¶

Search and filter provider records with pagination.

Endpoint: GET /provider-tables/

Query Parameters:

Response:

{
  "data": [
    {
      "id": 1,
      "provider_ccn": "010001",
      "national_provider_identifier": "1234567890",
      "effective_date": "2024-01-01",
      "termination_date": "2024-12-31",
      "table_name": "ipsf",
      "record_status": "active",
      "provider_type": "Hospital"
    }
  ],
  "count": 100
}

Example Requests:

# Search IPSF for active providers in NY
curl -H "Authorization: API_KEY..." \
  "https://api.example.com/api/v1/provider-tables/?table=ipsf&state=NY&active_only=true"

# Search by CCN
curl -H "Authorization: API_KEY..." \
  "https://api.example.com/api/v1/provider-tables/?provider_ccn=010001"

Get Filter Options¶

Retrieve available filter options for a specific table.

Endpoint: GET /provider-tables/filters/options

Query Parameters:

Response:

{
  "states": ["AL", "AK", "AZ"],
  "fiscal_years": [2024, 2023]
}

Get Suggestions¶

Get autocomplete suggestions for providers.

Endpoint: GET /provider-tables/suggestions

Query Parameters:

Response:

{
  "suggestions": [
    {
      "value": "1234567890",
      "label": "1234567890 - GENERAL HOSPITAL",
      "type": "base"
    }
  ]
}

Lookup Provider¶

Lookup provider records by NPI, CCN, or custom ID.

Endpoint: GET /provider-tables/lookup

Query Parameters:

Response:

{
  "base_matches": [],
  "custom_matches": []
}

Get Table Metadata¶

Retrieve field metadata for a specific table.

Endpoint: GET /provider-tables/{table}/metadata

Path Parameters:

Response:

{
  "provider_ccn": {
    "description": "CMS Certification Number",
    "type": "string"
  }
}

Get Single Record¶

Retrieve a specific provider record by ID.

Endpoint: GET /provider-tables/{table}/{record_id}

Path Parameters:

Response:

Returns the full IPSF or OPSF record object.

Get Provider Versions¶

Retrieve all versions of a provider's record.

Endpoint: GET /provider-tables/{table}/providers/versions

Path Parameters:

Query Parameters:

Note: Either provider_ccn or national_provider_identifier must be provided.

Response:

List of provider record versions.

Error Handling¶