Billing class (professional or institutional)

Provider entity type (individual or group)

Year and month specifier for a time period.

Month number, 1-12 (1=January, 12=December).

Use the Authorization header with a 'Bearer ' prefix and your API key.

Authorization

PayerPrice's healthcare price transparency APIs grant users access to real-time negotiated rates, comprehensive provider information, and market percentiles throughout the United States.

These APIs are specifically designed to facilitate reimbursement analytics, enhance provider directories, and streamline fee schedule retrieval.

PayerPrice API Documentation

Search for **market-level aggregate statistics** and benchmarks. This endpoint provides aggregated market data such as percentiles (50th, 75th, 90th, 95th), averages, min/max values across a market segment. Use this endpoint to understand market pricing trends and competitive positioning.

Successful query execution - returns an array of market benchmark results

Invalid request parameters or query limits exceeded.

User not authenticated or invalid API key

User does not have permission to access this endpoint

**[ALPHA]** Search for **provider-level negotiated rates** by taxonomy and location. This endpoint returns individual rate records grouped by TIN, billing code, and payer. Use this endpoint to analyze rate distributions and identify specific rate values across a market segment. Note: This API is in Alpha and may change without notice.

Successful query execution - returns an array of market rate results

Fuzzy search for NPIs by name, primary taxonomy, state, county, or entity type.

Retrieve provider information for one or more National Provider Identifiers (NPIs).

Retrieve the list of normalized plan names for a given payer, ordered by frequency (most common first).

Search for **provider-specific negotiated rates**. Use this endpoint to find the actual negotiated rates for specific providers identified by their NPI, TIN, or CCN. This is ideal for fee schedule retrieval and provider-specific pricing analysis.

Successful query execution - returns an array of provider-specific rate results

Search for negotiated rates with flexible filtering and aggregation options.

Filter and aggregation criteria. Uses the internal form data format with ValueObjects.

Create a new batch report for detailed healthcare rate analysis. Reports are processed asynchronously and can contain large datasets.

**Workflow:**
1. Call PUT /api/v1/report/metadata to create a report with filter criteria → returns a `reportId` (UUID)
2. Call POST /api/v1/report/reportData with the `reportId` to retrieve data (with column selection, pagination, aggregation)

**Report Types (benchmarkType):**
- `marketOverview`: Analyze negotiated rates across a geographic area by payer, billing code, and taxonomy. Requires states + taxonomies.
- `dataQuery`: Flexible data exploration across all rate data. Requires npis or tins.
**Nullable Fields Convention:** Fields set to `null` mean 'no filter applied' (include all). Fields set to `[]` (empty array) also mean no filter but are used when the field doesn't support null.

**Note:** Reports may take a few seconds to generate depending on data volume. Use `waitUntilReportReadyTimeoutSeconds` in the POST request to wait for completion.

Report creation accepted. The report is being generated asynchronously. Use the returned `reportId` with the POST endpoint to retrieve data.

Invalid request parameters. The request body failed validation (e.g., missing required benchmarkType, invalid enum values, malformed arrays).

Unauthorized. The API key is missing, invalid, or the user does not have permission to create reports.

Retrieve data from an existing report using the report ID from the PUT /api/v1/report/metadata endpoint.

**Workflow:**
1. Provide the `id` (UUID) returned from the PUT /api/v1/report/metadata request
2. Specify which columns to retrieve via `getRawData.columnAggregations`
3. Optionally apply aggregation functions (e.g., percentiles, averages) to numeric columns
4. Use `limit` for pagination and `sorting` for ordering

**Column Selection & Aggregation:**
- List columns in `columnAggregations` to select which fields appear in output rows
- Columns without `aggregation` become GROUP BY columns when any column has an aggregation
- Use `outputColumn` to rename aggregated columns (required when aggregating the same column multiple times)

**Async Handling:**
- Use `waitUntilReportReadyTimeoutSeconds` to poll until the report finishes processing
- If the report is not ready within the timeout, returns HTTP 408 (Request Timeout)

**Response Structure:**
The response wraps report data in `{ success, code, message }` where `message` is an array of report objects. Each report object contains metadata and a `rawData` field with `{ rows, totalNumRows }`.

Report data successfully retrieved. The response contains report metadata and the requested data rows.

Invalid request parameters. Examples: missing report ID, invalid column names, invalid filter format, invalid sorting configuration.

Unauthorized. The API key is missing, invalid, or the user lacks permission to access this report.

Request Timeout. The report is still being generated and the `waitUntilReportReadyTimeoutSeconds` was exceeded. Retry the POST request with the same parameters after a short delay.

Fuzzy search for TINs by name, provider taxonomy codes, state, or TIN type (ein/npi).

Retrieve provider information for one or more Taxpayer Identification Numbers (TINs). **Note:** CMS allows insurers to report provider TINs using either an NPI or Employer Identification Number (EIN).