---
title: "Negotiated rates for codes near a place"
method: POST
path: "/v1/rates"
tags: ["rates"]
---

# Negotiated rates for codes near a place

`POST /v1/rates`

## Request

- Base URL: `https://api.ticexplorer.com`
- URL: `https://api.ticexplorer.com/v1/rates`
- Auth: HTTP bearer

Coverage × codes × providers-or-area → self-describing rate rows + summary. First use of a plan's rate files
indexes them just in time (up to `wait_seconds`); later calls are fast.

**Workflows**

Workflow `compare-places`, step 3/3 `rates`: Compare what the plan pays different nearby providers for the same service.
- Purpose: Rows are comparable within the same billing component and place of service; a global rate already includes 26 + TC.
- Call after: `find_codes`

## Request body

- RatesRequest
  - `coverage` Coverage, required
    - `type` 'plan' | 'medicare' | 'hospital': plan = a plan from find_plan (insurer rate files); medicare = Original Medicare fee schedule; hospital = hospitals' own price files (Medicare Advantage, Medicaid, cash/self-pay): each hospital's posted rate per payer/plan as the hospital wrote it (not necessarily the person's plan), mostly facility charges; cash = its discounted cash price, not the gross charge. price_claim does not accept hospital.
    - `plan_id` string, nullable: Required when type = plan; from find_plan.
    - `hospital_coverage` string, nullable: For type = hospital: medicare_advantage | medicaid | cash | a payer name.
  - `codes` string[], required: Billing codes from find_codes (CPT/HCPCS, or an APC number for hospital case rates).
  - `providers` Providers
    - `tins` string[]: Billing entity tax IDs (from find_providers), e.g. 84-1179794.
    - `npis` string[]: NPIs of locations or clinicians.
    - `names` string[]: Substring match on billing entity / location names.
  - `area` Area, required
    - `zip` string, required: 5-digit ZIP the person is near.
    - `miles` number: Search radius in miles.
  - `limit` integer
  - `cursor` integer: Pagination cursor from next_cursor.
  - `wait_seconds` integer: How long to wait for rate files being indexed for the first time.
  - `label` string, nullable: Echoed back in batch results.

## Response `200`

Successful Response

- RatesResult
  - `data` RateRow[], required
    - `code` string, required
    - `code_type` string, required
    - `billing_entity` object, required: {tin, name, is_hospital}: prices belong to billing entities.
    - `location` object, required
    - `price` Price, required
      - `kind` string, required: negotiated | fee_schedule | derived | per_diem | percent_of_charges | placeholder | algorithm ...
      - `amount` number, nullable: Allowed dollars per unit; null when not a dollar price.
      - `percent` number, nullable
      - `unit` string, required: per_service | per_day | per_apc_case | percent_of_billed_charges | none
      - `is_dollar_price` boolean, required
    - `billing` Billing, required
      - `billing_class` string, nullable: professional (clinician claim) | institutional (facility claim)
      - `setting` string, nullable
      - `modifiers` string[]
      - `component` string, required: global | professional_component | technical_component | professional | facility | drug
      - `applies_when` string, required
      - `place_of_service` string, required: non_facility | facility | mixed | unspecified
    - `hospital_outpatient` object, nullable: APC, status indicator, packaging (institutional rows).
    - `benchmark` object, nullable: Medicare amount for the same service/setting + percent_of_medicare.
    - `flags` string[]
    - `quality` object, nullable: {score 1-5, reason}: 5 corroborated by the hospital's own file, 4 consistent with Medicare band, 3 unchecked / not corroborated, 2 unusual, 1 not a usable dollar price (guide://fields).
    - `hospital_file_rate` object, nullable: Hospital rows: the same hospital's own price file for this payer and code (amount, plan_as_written, agreement, difference_percent).
    - `evidence` object, required
    - `provenance` object, required: payer, plan, files, insurer_date_label vs retrieved_at, future_dated_label.
  - `next_cursor` integer, nullable
  - `total_rows` integer, required
  - `summary` object[]
  - `cheapest_sites` object[]: Per code x component: the cheapest real places to go (site, address, miles to the site, TIN, amount, quality).
  - `hospital_file_check` object, nullable: How many hospital rows were compared with the hospitals' own price files, and how many agree.
  - `medicare_reference` object, nullable: coverage medicare: per code OPPS wage-adjusted APC, estimated lab fee, ASP drug limit.
  - `coverage` object, nullable
  - `needs` Need[]
    - `field` string, required: The missing input or condition, e.g. which_insurer, place_of_service, wait.
    - `why` string, required: Why it changes the answer and what to do.
  - `next_steps` string[]

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests

---

[API](https://skmtc.dev/ticexplorer/apis/tic-explorer-api.md) · [All operations](https://skmtc.dev/ticexplorer/apis/tic-explorer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ticexplorer/apis/tic-explorer-api/revisions/9800d20135b9?raw)