# PayerPrice API Documentation

PayerPrice's healthcare price transparency APIs give you access to negotiated rates, provider information, and market benchmarks across the United States. Use them to power reimbursement analytics, build provider directories, and retrieve fee schedules.

## Start here

1. [Log in](https://app.payerprice.com/app/login?utm_source=api_docs&utm_medium=referral&utm_campaign=login&redirectTo=%2Fapi%2Fdoc) or [sign up](https://app.payerprice.com/app/sign-up?utm_source=api_docs&utm_medium=referral&utm_campaign=signup&redirectTo=%2Fapi%2Fdoc) to get an API key. Then find it under [**Your API Keys**](/api/doc#description/your-api-keys).
2. Make a first request to list available payers and data periods:

```bash
curl https://api.payerprice.com/api/v1/payers \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

3. The response is an array of objects with a `payer` name and `yearMonths` entries. Use a returned payer and period when building a pricing request. [See the payer endpoint](/api/doc#tag/payer-apis/GET/api/v1/payers).
4. Next, [get market benchmarks](/api/doc#tag/pricing-apis/POST/api/v1/market/benchmarks) for a comparable market or [get provider rates](/api/doc#tag/pricing-apis/POST/api/v1/provider/rates) for a specific NPI, TIN, or CCN.

Requests made with an API key can consume credits. Check the credit balance and [usage dashboard](https://app.payerprice.com/app/profile?tab=api-usage) before choosing **Test Request**. Test requests are sent only when you click that button.

## Integration essentials

- Send `Authorization: Bearer YOUR_API_KEY` over HTTPS. A missing or invalid key returns `401`; a forbidden request returns `403`.
- Invalid filters can return `400`. Insufficient API credit returns `402`. Rate limiting returns `429`; back off before retrying. Retry reads after transient failures, but do not blindly repeat create, update, or delete requests.
- Pagination and asynchronous processing vary by endpoint. Follow each operation's request and response fields. Report creation can finish after the initial request; use its documented status and data-retrieval workflow.
- API paths use `/api/v1`. The OpenAPI version describes this contract; payer `yearMonths` describe available source-data periods. These are separate versions.

## OpenAPI specification

[Download the OpenAPI specification](/api/doc/openapi.json) using a signed-in browser session or an `Authorization: Bearer YOUR_API_KEY` header. Credentials are never embedded in the response. [Read Markdown docs](/api/doc.md) or [the API index for agents](/llms.txt).

## Authentication

All requests must include an API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

## Base URL

`https://api.payerprice.com`

## Payer APIs

Retrieve payer-level metadata — supported payers, available data periods, and plan names for a given insurance payer.

### GET /api/v1/payers {#get-apiv1payers}

Retrieve supported payers and available year/month source-data periods. A listed period means data is available for that payer; it does not establish a contract effective date for any returned rate.

#### Responses

- **200**: Array of payer availability objects
- **401**: Missing or invalid API key.
- **402**: Insufficient API credit for an API-key request.
- **403**: The API key cannot access this endpoint.
- **429**: Request rate limit exceeded; retry after backing off.

---

### POST /api/v1/payer/plans {#post-apiv1payerplans}

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

#### Request Body

- `payer` **(required)**: Payer enum: BCBS, United, Aetna, Cigna, FirstHealth, BannerHealth, MeritainHealth, Centene, Fidelis, Ambetter... - 

#### Example: Query BCBS plan names

```json
{
  "payer": "BCBS"
}
```

#### Responses

- **200**: Array of payer plan objects
- **400**: Invalid payer

---

## Provider APIs

Look up and search for healthcare providers by NPI, TIN, name, location, taxonomy, entity type, in-network payers, or affiliations. Supports both direct lookups and fuzzy search — suited for building provider directories and network analysis.

### POST /api/v1/npis {#post-apiv1npis}

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

#### Request Body

- `npis` **(required)**: array - Array of NPI numbers to query
- `includeFields`: array - List of fields to include in the response

#### Example 1: Query NPI information

```json
{
  "npis": [
    1073502985
  ],
  "includeFields": [
    "npi",
    "name",
    "state",
    "counties",
    "entityType",
    "payers",
    "tins",
    "primaryTaxonomyCode"
  ]
}
```

#### Responses

- **200**: Array of NPI information objects
- **400**: Invalid request parameters

---

### POST /api/v1/npiSearch {#post-apiv1npiSearch}

Fuzzy search for NPIs by name or NPI. Optionally filter results by taxonomy, state, county, or entity type.

#### Request Body

- `searchTerm`: string - Search term to match against provider names or NPIs.
- `matchFields`: array - Fields used for text matching. Defaults to displayName, ccns, otherName, and tins.
- `includeFields`: array - List of fields to include in the response
- `taxonomyCodes`: array - List of taxonomy codes to filter by
- `states`: array - List of two-letter state codes to filter by
- `counties`: array - List of county names to filter by
- `entityTypes`: array - Filter by provider entity types
- `inNetworkPayers`: array of Payer enum: BCBS, United, Aetna, Cigna, FirstHealth, BannerHealth, MeritainHealth, Centene, Fidelis, Ambetter... - Restrict results to entries whose inNetworkPayers contains at least one of the given payers.
- `limit`: number - Maximum number of results to return; requests above 3,000 return at most 3,000.

#### Example 1: Search for NPI by name

```json
{
  "searchTerm": "Chu Chen",
  "includeFields": [
    "npi",
    "displayName",
    "state",
    "inNetworkPayers",
    "tins"
  ],
  "states": [
    "MA"
  ],
  "limit": 50
}
```

#### Responses

- **200**: List of matching providers
- **400**: Invalid request parameters

---

### POST /api/v1/ccns {#post-apiv1ccns}

Retrieve hospital information keyed by CMS Certification Number (CCN).

#### Request Body

- `ccns` **(required)**: array - Six-digit CMS Certification Numbers.
- `ccnCategories`: array - 
- `ccnFacilityTypes`: array - 
- `includeFields`: array - Optional hospital fields to include.

#### Responses

- **200**: Hospital information keyed by CCN; an empty lookup returns an empty object.
- **400**: Invalid request body or CCN

---

### POST /api/v1/ccnSearch {#post-apiv1ccnSearch}

Search hospitals by name or CCN, with optional state, category, and facility type filters.

#### Request Body

- `searchTerms`: array - 
- `state`: State enum: AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA... - 
- `ccn`: string - Exact six-digit CCN to match.
- `limit`: integer - Maximum number of results to return; requests above 10,000 return at most 10,000.
- `ccnFacilityTypes`: array - 
- `ccnCategories`: array - 
- `includeFields`: array - 

#### Responses

- **200**: Matching hospitals, at most the requested limit.
- **400**: Invalid request body, state, or CCN

---

### POST /api/v1/tins {#post-apiv1tins}

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).

#### Request Body

- `tins`: array - Array of TIN numbers to query
- `includeFields`: array - List of fields to include in the response. Use relatedGroupNpis to return a sample of group NPIs associated with each TIN.

#### Example 1: Query TIN information

```json
{
  "tins": [
    42103590,
    42484572,
    42774441
  ],
  "includeFields": [
    "tinName",
    "states",
    "relatedGroupNpis"
  ]
}
```

#### Responses

- **200**: Successfully retrieved TIN information
- **400**: Invalid request parameters

---

### POST /api/v1/tinSearch {#post-apiv1tinSearch}

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

#### Request Body

- `searchTerm`: string - Term to match against organization names (fuzzy match). Provide either `searchTerm` (single) or `searchTerms` (multiple).
- `searchTerms`: array - Multiple terms to match against organization names. Use instead of `searchTerm` when querying several names at once.
- `matchFields`: array - Fields used for text matching. Defaults to tinName and tinValue.
- `taxonomyCodes`: array - Taxonomy codes to filter by (optional).
- `states`: array - Two-letter state codes to filter by (optional).
- `tinTypes`: array - TIN type filter. `ein` = Employer Identification Number, `npi` = National Provider Identifier.
- `limit`: number - Maximum number of results to return; requests above 3,000 return at most 3,000.
- `includeFields`: array - Fields to include in the response.

#### Example 1: Search for TIN by name, type and state

```json
{
  "searchTerm": "Medical Group",
  "tinTypes": [
    "ein"
  ],
  "states": [
    "CA"
  ],
  "includeFields": [
    "tinValue",
    "tinType",
    "tinName",
    "tinState"
  ],
  "limit": 50
}
```

#### Responses

- **200**: List of matching TINs
- **400**: Invalid request parameters

---

## Pricing APIs

Retrieve negotiated rates and market statistics. Includes market-wide benchmarks (percentiles, averages, min/max), provider-specific rates (by NPI, TIN, or CCN), individual rate records across a market segment, and hospital-published rates from price transparency files.

### POST /api/v1/market/benchmarks {#post-apiv1marketbenchmarks}

Search for market-level aggregate statistics and benchmarks. Results summarize published rates in the selected payer, geography, taxonomy, billing-code, and period cohort; they are not prices for a specific provider or a guarantee of claim payment. Keep billing class, service code, modifier, and negotiated type comparable when interpreting percentiles. An empty result may reflect an overly narrow filter or missing published data.

#### Request Body

- `filters` **(required)**: object - 
  - `states` **(required)**: array of State enum: AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA... - Array of US state codes to filter by (required for market benchmarks).
  - `zipCodes`: array - 5-digit US ZIP codes to filter results by provider location (e.g., 02451, 90210).
  - `taxonomyCodes` **(required)**: array of TaxonomyCode enum: 193200000X, 193400000X, 207K00000X, 207KA0200X, 207KI0005X, 207L00000X, 207LA0401X, 207LC0200X, 207LH0002X, 207LP2900X... - Array of provider taxonomy codes (required for market benchmarks).
  - `payers` **(required)**: array of Payer enum: BCBS, United, Aetna, Cigna, FirstHealth, BannerHealth, MeritainHealth, Centene, Fidelis, Ambetter... - Array of payer identifiers (required).
  - `billingCodeAndTypes` **(required)**: array of objects - Specific billing codes to search for (required).
    - `code` **(required)**: string - Billing code (e.g., 99213)
    - `type` **(required)**: BillingCodeType enum: CPT, HCPCS, RC, MS-DRG, APR-DRG, LOCAL, CSTM-ALL - 
  - `entityTypes`: array of EntityType enum: individual, group - Individual or group practice filter (optional)
  - `billingClasses`: array of BillingClass enum: professional, institutional - Professional vs institutional (optional)
  - `serviceCodes`: array of ServiceCode enum: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10... - Place of service codes (e.g., office, hospital, telehealth) to search for (optional)
  - `billingCodeModifiers`: array of BillingCodeModifier enum: none, TC, 26 - CPT modifiers to search for (optional)
  - `negotiatedTypes`: array of NegotiatedType enum: negotiated, derived, fee schedule, percentage, per diem - Rate negotiation types to search for (optional)
  - `yearMonths`: array of objects - Year/month periods to filter by (optional). Leave empty to query the latest available data; supply specific periods only when comparing rates across time.
    - `year` **(required)**: number - Year (e.g., 2025)
    - `month` **(required)**: number - Month (1-12)
  - `planNames`: array - Normalized plan names to narrow results to specific insurance plans (optional).
  - `networks`: array - Individual (un-normalized) network names to narrow results to specific networks, exactly as reported in the payer transparency file (optional).
- `metrics` **(required)**: object - 
  - `aggregations` **(required)**: array - Statistical metrics to calculate (required for market benchmarks)
  - `comparedTo`: string (none, medicare_2025, medicare_2024, medicare_2023, medicare_2022, medicare_2021, medicare_2020) - Optional Medicare comparison baseline for the benchmark values.
- `groupBy`: array of GroupByField enum: payer, npiState, taxonomyCode, entityType, negotiatedType, billingClass, billingCodeType, billingCode, billingCodeGroup, billingCodeSubgroup... - Fields to group results by (optional). Including network returns a separate benchmark group for each individual network name.

#### Example: Market Benchmarks for Office Visits

```json
{
  "filters": {
    "states": [
      "MA"
    ],
    "taxonomyCodes": [
      "208000000X"
    ],
    "payers": [
      "United",
      "Cigna"
    ],
    "billingCodeAndTypes": [
      {
        "code": "99213",
        "type": "CPT"
      },
      {
        "code": "99214",
        "type": "CPT"
      }
    ],
    "serviceCodes": [
      "11"
    ],
    "negotiatedTypes": [
      "negotiated",
      "fee schedule"
    ],
    "billingClasses": [
      "professional"
    ]
  },
  "metrics": {
    "aggregations": [
      "percentile_50",
      "percentile_75",
      "percentile_90",
      "percentile_95"
    ]
  },
  "groupBy": [
    "payer",
    "billingCode"
  ]
}
```

#### Responses

- **200**: Array of market benchmark results.
- **400**: Invalid request parameters or query limits exceeded.
- **401**: User not authenticated or invalid API key
- **403**: User does not have permission to access this endpoint

---

### POST /api/v1/provider/rates {#post-apiv1providerrates}

Search for published provider-specific negotiated rates by NPI, TIN, or CCN. Preserve the matched provider identifier, payer, plan or network, billing code and type, billing class, service code, modifier, negotiated type, and source period when comparing rows. Multiple rows for one payer and code may represent different contracts or contexts. A published rate does not by itself establish a claim's allowed or paid amount. For cursor pagination, send `pagination: {}` (default page size 1,000), then repeat the same request with `pagination.cursor` set to the returned `nextCursor` until it is null. Each page is billed separately. The organization's configured maximum can be lower or higher than 1,000, up to 10,000. Without `pagination`, the legacy array response is unchanged.

#### Request Body

- `providers` **(required)**: object - Provider identifiers to query rates for. At least one provider identifier (NPI, TIN, or CCN) must be specified.
  - `npis`: array - NPIs to query negotiated rates for (optional, specify at least one of npis, tins, or ccns)
  - `tins`: array - TINs to query negotiated rates for (optional, specify at least one of npis, tins, or ccns)
  - `ccns`: array - CCNs to query negotiated rates for (optional, specify at least one of npis, tins, or ccns)
- `payers` **(required)**: array of Payer enum: BCBS, United, Aetna, Cigna, FirstHealth, BannerHealth, MeritainHealth, Centene, Fidelis, Ambetter... - Array of payer identifiers (required)
- `billingCodeAndTypes` **(required)**: array of objects - Specific billing codes to search for (optional)
  - `code` **(required)**: string - Billing code (e.g., 99213)
  - `type` **(required)**: BillingCodeType enum: CPT, HCPCS, RC, MS-DRG, APR-DRG, LOCAL, CSTM-ALL - 
- `billingClasses`: array of BillingClass enum: professional, institutional - Professional vs institutional (optional)
- `serviceCodes`: array of ServiceCode enum: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10... - Place of service codes to filter by (optional)
- `billingCodeModifiers`: array of BillingCodeModifier enum: none, TC, 26 - Billing code modifiers to filter by (optional)
- `negotiatedTypes`: array of NegotiatedType enum: negotiated, derived, fee schedule, percentage, per diem - Rate negotiation types to search for (optional)
- `yearMonths`: array of objects - Year/month periods to filter by (optional). Leave empty to query the latest available data; supply specific periods only when comparing rates across time.
  - `year` **(required)**: number - Year (e.g., 2025)
  - `month` **(required)**: number - Month (1-12)
- `planNames`: array - Normalized plan names to narrow results to specific insurance plans (optional).
- `networks`: array - Individual (un-normalized) network names to narrow results to specific networks, exactly as reported in the payer transparency file (optional).
- `groupBy`: array of ProviderGroupByField enum: payer, npiState, taxonomyCode, entityType, negotiatedType, billingClass, billingCodeType, billingCode, billingCodeGroup, billingCodeSubgroup... - Fields to group results by (optional). Including network or planName adds the corresponding deduplicated array without splitting otherwise-identical provider-rate groups. planName arrays are sorted and limited to at most 30 names.
- `pagination`: object - Opt in to cursor pagination. Omit for the legacy array response.
  - `pageSize`: integer - Rows per page. Limited by the organization's configured maximum; defaults to the smaller of 1,000 and that maximum.
  - `cursor`: string - Opaque nextCursor from the preceding page. Keep every other request field unchanged.

#### Example 1: Rates for Specific Provider (NPI)

```json
{
  "providers": {
    "npis": [
      1073502985
    ]
  },
  "payers": [
    "United"
  ],
  "billingCodeAndTypes": [
    {
      "code": "99213",
      "type": "CPT"
    },
    {
      "code": "99214",
      "type": "CPT"
    }
  ],
  "serviceCodes": [
    "11"
  ],
  "negotiatedTypes": [
    "negotiated",
    "fee schedule"
  ],
  "billingClasses": [
    "professional"
  ],
  "groupBy": [
    "payer",
    "billingCode",
    "serviceCode",
    "billingCodeModifier"
  ]
}
```

#### Example 2: Rates for Provider Group (TIN)

```json
{
  "providers": {
    "tins": [
      123456789
    ]
  },
  "payers": [
    "United",
    "Cigna"
  ],
  "billingCodeAndTypes": [
    {
      "code": "99211",
      "type": "CPT"
    },
    {
      "code": "99213",
      "type": "CPT"
    },
    {
      "code": "99214",
      "type": "CPT"
    },
    {
      "code": "99215",
      "type": "CPT"
    }
  ],
  "billingClasses": [
    "professional"
  ],
  "groupBy": [
    "payer",
    "billingCode"
  ]
}
```

#### Responses

- **200**: Legacy array response, or {data, nextCursor} when pagination is supplied.
- **400**: Invalid request parameters or query limits exceeded.
- **401**: User not authenticated or invalid API key
- **403**: User does not have permission to access this endpoint

---