The Price Transparency v2 API from H1 (Ribbon Health) — 7 location-first operations for negotiated-rate shopping. Prices are scoped to a facility rather than to a provider, carriers use string business ids rather than v1 UUIDs, and geographic search requires an explicit address or lat/lng. Harvested from the OpenAPI 3.1.0 definitions H1 publishes verbatim inside each API reference page.
openapi: 3.1.0
info:
title: H1's API — Price Transparency v2
version: 1.0.0
description: "An API for interacting with the data provided by Ribbon Health, including information about healthcare\
\ providers,\nlocations, insurances, and more.\n\n## Price Transparency v2\n\nLocation-first negotiated rate\
\ endpoints live under `/v2/*` (separate from legacy\n`/v1/pricing/*`). Use them to:\n\n1. Look up procedures,\
\ care clusters, and carriers (`GET /v2/procedures`,\n `/v2/care-clusters`, `/v2/carriers`)\n2. Get prices\
\ for a known location (`GET /v2/locations/{location_id}/pricing/...`)\n3. Shop by geography (`GET /v2/pricing/locations/...`)\n\
\n**Key differences from v1:** prices are location-scoped (not provider-first);\ncarriers use string business\
\ ids (not v1 carrier UUIDs); every v2 response uses\nthe same envelope (`parameters`, `total_count`, `page`,\
\ `page_size`, `data`);\ngeo search requires an explicit `address` or `lat`+`lng` (no silent default).\n\nSee\
\ the **Price Transparency v2** tag for full endpoint reference.\n"
x-apievangelist-provenance:
harvested: '2026-08-14'
method: searched
source: https://ribbon.readme.io/reference/{getv2procedures,getv2careclusters,getv2carriers,getv2locationprocedurepricing,getv2locationcareclusterpricing,getv2pricinglocationprocedures,getv2pricinglocationcareclusters}.md
note: Assembled from the OpenAPI 3.1.0 definitions the provider publishes verbatim inside each ReadMe reference
page (each page embeds a single-operation slice of H1's live spec). Only the paths were unioned; no operation,
parameter, schema or description was written, edited or invented. servers[], security and components.securitySchemes
are the provider's own. This surface is documented and live but is absent from every other OpenAPI in this
repo.
servers:
- url: https://api.ribbonhealth.com
security:
- BearerAuth: []
tags:
- name: Price Transparency v2
description: Location-first negotiated-rate endpoints under /v2/*.
paths:
/v2/procedures:
get:
summary: List Procedures (v2)
description: "Browse or search the Price Transparency v2 procedure code dictionary.\n\nUse this to resolve\
\ a CPT (or other) code before pricing lookups, or to\ndiscover which care clusters a procedure belongs\
\ to. This endpoint does\n**not** return dollar amounts.\n\n#### Example Use Case\nLook up CPT `27447` to\
\ confirm its description and see that it belongs to\nthe `JOINT_REPLACEMENT` care cluster before calling\
\ a pricing endpoint.\n\n#### Notes\n- Requires Price Transparency access (`doctors.can_price_transparency`).\n\
- Rate limited to 1,000 requests per minute.\n- All Price Transparency v2 endpoints share the same response\
\ envelope:\n `parameters`, `total_count`, `page`, `page_size`, and `data`.\n"
operationId: getV2Procedures
tags:
- Price Transparency v2
parameters:
- name: procedure_code
in: query
required: false
description: Exact procedure code filter (for example `27447`).
schema:
type: string
example: '27447'
- name: procedure_code_scheme
in: query
required: false
description: 'Exact match on procedure coding system (for example `CPT` or `HCPCS`).
'
schema:
type: string
example: CPT
- name: procedure_description
in: query
required: false
description: Case-insensitive substring match on procedure description.
schema:
type: string
example: knee
- name: care_cluster_code
in: query
required: false
description: Filter to a specific care cluster by its business code (for example `JOINT_REPLACEMENT`).
schema:
type: string
example: JOINT_REPLACEMENT
- name: care_cluster_description
in: query
required: false
description: 'Match on care cluster display description. Case-insensitive substring on
dictionary endpoints; case-insensitive exact match on DB-backed pricing
endpoints; case-sensitive exact match on Elasticsearch search endpoints.
'
schema:
type: string
example: Joint Replacement
- $ref: '#/paths/~1v2~1carriers/get/parameters/2'
- $ref: '#/paths/~1v2~1carriers/get/parameters/3'
responses:
'200':
description: Matching procedure dictionary records.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1v2~1carriers/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
type: object
description: A procedure code from the Price Transparency v2 dictionary.
required:
- code
- code_scheme
- description
properties:
code:
type: string
description: Procedure code.
example: '27447'
code_scheme:
type: string
description: Coding system (for example `CPT`).
example: CPT
description:
type: string
description: Human-readable procedure description.
example: Total knee arthroplasty
care_clusters:
type: array
description: 'Present only when the procedure belongs to one or more care clusters.
'
items:
type: object
required:
- care_cluster_code
- care_cluster_description
properties:
care_cluster_code:
type: string
example: JOINT_REPLACEMENT
care_cluster_description:
type: string
example: Joint Replacement
example:
- code: '27447'
code_scheme: CPT
description: Total knee arthroplasty
care_clusters:
- care_cluster_code: JOINT_REPLACEMENT
care_cluster_description: Joint Replacement
example:
parameters:
procedure_code: '27447'
procedure_code_scheme: CPT
total_count: 1
page: 1
page_size: 20
data:
- code: '27447'
code_scheme: CPT
description: Total knee arthroplasty
care_clusters:
- care_cluster_code: JOINT_REPLACEMENT
care_cluster_description: Joint Replacement
'400':
description: Invalid query parameters.
content:
application/json:
schema:
$ref: '#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema'
'403':
description: The caller does not have Price Transparency access.
content:
application/json:
schema:
$ref: '#/paths/~1v2~1carriers/get/responses/403/content/application~1json/schema'
/v2/care-clusters:
get:
summary: List Care Clusters (v2)
description: 'Browse care cluster definitions and the procedures each cluster includes.
A care cluster is a curated group of related procedures that together
represent a care episode (for example joint replacement). Use this
dictionary before querying bundle prices.
#### Example Use Case
Search for clusters matching `"joint"` to find `JOINT_REPLACEMENT` and see
which CPT codes are expected in that bundle.
'
operationId: getV2CareClusters
tags:
- Price Transparency v2
parameters:
- $ref: '#/paths/~1v2~1procedures/get/parameters/3'
- $ref: '#/paths/~1v2~1procedures/get/parameters/4'
- $ref: '#/paths/~1v2~1procedures/get/parameters/0'
- $ref: '#/paths/~1v2~1carriers/get/parameters/2'
- $ref: '#/paths/~1v2~1carriers/get/parameters/3'
responses:
'200':
description: Matching care cluster definitions.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1v2~1carriers/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
type: object
description: A care cluster definition from the Price Transparency v2 dictionary.
required:
- care_cluster_code
- care_cluster_description
- procedures
properties:
care_cluster_code:
type: string
description: Stable business code for the cluster.
example: JOINT_REPLACEMENT
care_cluster_description:
type: string
description: Display name for the cluster.
example: Joint Replacement
procedures:
type: array
description: Member procedures that make up this care episode.
items:
type: object
required:
- code
- code_scheme
- description
properties:
code:
type: string
example: '27447'
code_scheme:
type: string
example: CPT
description:
type: string
example: Total knee arthroplasty
example:
- care_cluster_code: JOINT_REPLACEMENT
care_cluster_description: Joint Replacement
procedures:
- code: '27447'
code_scheme: CPT
description: Total knee arthroplasty
example:
parameters:
care_cluster_description: joint
total_count: 1
page: 1
page_size: 20
data:
- care_cluster_code: JOINT_REPLACEMENT
care_cluster_description: Joint Replacement
procedures:
- code: '27447'
code_scheme: CPT
description: Total knee arthroplasty
'400':
description: Invalid query parameters.
content:
application/json:
schema:
$ref: '#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema'
'403':
description: The caller does not have Price Transparency access.
content:
application/json:
schema:
$ref: '#/paths/~1v2~1carriers/get/responses/403/content/application~1json/schema'
/v2/carriers:
get:
summary: List Carriers (v2)
description: 'List carriers available in the Price Transparency v2 pricing data set.
Use this to discover valid `carrier_id` values for pricing filters.
#### Important
These identifiers are **not** the same as v1 [`/v1/pricing/carriers`](./getpricingcarriers)
UUIDs. Always resolve carriers through this endpoint (or a curated customer
mapping) when working with v2.
'
operationId: getV2Carriers
tags:
- Price Transparency v2
parameters:
- name: carrier_id
in: query
required: false
description: Exact match on carrier business id.
schema:
type: string
example: '78110'
- name: carrier_name
in: query
required: false
description: 'Match on carrier display name. Case-insensitive substring on
`/v2/carriers`; case-insensitive exact match on DB-backed pricing endpoints;
case-sensitive exact match on Elasticsearch search endpoints.
'
schema:
type: string
example: Aetna
- name: page
in: query
required: false
description: 'Page of results to return. Values below `1` are treated as `1`.
'
schema:
type: integer
minimum: 1
default: 1
example: 1
- name: page_size
in: query
required: false
description: 'Number of results per page. Hard-capped at **100**.
'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
example: 20
responses:
'200':
description: Matching carriers.
content:
application/json:
schema:
allOf:
- type: object
description: 'Standard response envelope for all Price Transparency v2 endpoints.
Pagination fields are always present; `parameters` echoes the non-null filters
that were applied (pagination keys are omitted from the echo).
'
required:
- parameters
- total_count
- page
- page_size
- data
properties:
parameters:
type: object
additionalProperties: true
description: Echo of non-null request filters (pagination omitted).
example:
code: '27447'
code_scheme: CPT
total_count:
type: integer
description: Total matching rows across all pages.
example: 1
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Page size used for this response.
example: 20
data:
type: array
description: Records for the current page.
items: {}
- type: object
properties:
data:
type: array
items:
type: object
description: 'An insurance carrier in the Price Transparency v2 data set.
Use `carrier_id` as the filter value on pricing endpoints.
'
required:
- carrier_id
- name
properties:
carrier_id:
type: string
description: Business id used in all v2 pricing filters.
example: '78110'
name:
type: string
description: Display name.
example: Aetna
example:
- carrier_id: '78110'
name: Aetna
example:
parameters:
carrier_name: aetna
total_count: 1
page: 1
page_size: 20
data:
- carrier_id: '78110'
name: Aetna
'400':
description: Invalid query parameters.
content:
application/json:
schema:
type: object
description: An error returned from the API
required:
- error
properties:
error:
type: object
required:
- status
- code
- message
properties:
status:
type: integer
description: The HTTP error code associated with this error
example: 400
code:
type: string
enum:
- invalid_query_params
- bad_request
message:
type:
- object
- string
description: 'An object representing what exactly went wrong. The keys available in this
object vary with the type of error returned.
'
example:
query:
_schema:
- parameters 'npis' and 'location_ids' cannot be used together
'403':
description: The caller does not have Price Transparency access.
content:
application/json:
schema:
type: object
description: You are not allow to make this request
required:
- error
properties:
error:
type: object
required:
- status
- code
- message
properties:
status:
type: integer
example: 403
code:
type: string
enum:
- permission_denied
message:
type: string
example: a trial account does not have access to this functionality
/v2/locations/{location_id}/pricing/procedures:
get:
summary: Location Procedure Pricing (v2)
description: 'Return all procedure-level negotiated rates for a single facility /
practice location, optionally filtered by carrier.
Results are ordered cheapest-first by `min`.
#### Example Use Case
Given location `1001` and carrier `78110`, list every procedure priced at
that site for that carrier, sorted from lowest to highest `min`.
#### Path parameter
`location_id` accepts either the integer location id **or** the location UUID.
Unknown values return HTTP 404.
#### Carrier filtering
Prefer `carrier_id` (from [`GET /v2/carriers`](./getv2carriers)).
`plan_id` is accepted in the contract but currently returns HTTP 501.
`carrier_id` and `plan_id` are mutually exclusive (HTTP 400 if both are sent).
'
operationId: getV2LocationProcedurePricing
tags:
- Price Transparency v2
parameters:
- name: location_id
in: path
required: true
description: 'The location to look up. Accepts either the integer location id **or** the location UUID.
'
schema:
type: string
example: '1001'
- $ref: '#/paths/~1v2~1pricing~1locations~1procedures/get/parameters/7'
- $ref: '#/paths/~1v2~1carriers/get/parameters/1'
- $ref: '#/paths/~1v2~1procedures/get/parameters/1'
- $ref: '#/paths/~1v2~1pricing~1locations~1procedures/get/parameters/9'
- $ref: '#/paths/~1v2~1carriers/get/parameters/2'
- $ref: '#/paths/~1v2~1carriers/get/parameters/3'
responses:
'200':
description: Procedure price records for the location.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1v2~1carriers/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
type: object
description: 'Location-scoped negotiated rate statistics for a single procedure and carrier.
'
required:
- procedure_code
- procedure_code_scheme
- procedure_description
- carrier_id
- carrier_name
- location_id
- min
- median
- avg
- max
properties:
procedure_code:
type: string
example: '27447'
procedure_code_scheme:
type: string
example: CPT
procedure_description:
type: string
example: Total knee arthroplasty
carrier_id:
type: string
example: '78110'
carrier_name:
type: string
example: Aetna
location_id:
type: string
description: Location id as a string.
example: '1001'
npi:
type:
- integer
- 'null'
description: Null for location-level records.
example: null
negotiated_type:
type: string
example: negotiated
negotiation_arrangement:
type: string
example: ffs
min:
type: number
format: float
example: 14200
median:
type: number
format: float
example: 16850
avg:
type: number
format: float
example: 17120.5
max:
type: number
format: float
example: 21400
care_cluster_codes:
type: array
description: Present when the procedure belongs to one or more care clusters.
items:
type: string
example:
- JOINT_REPLACEMENT
example:
parameters:
carrier_id: '78110'
location_id: '1001'
total_count: 1
page: 1
page_size: 20
data:
- procedure_code: '27447'
procedure_code_scheme: CPT
procedure_description: Total knee arthroplasty
carrier_id: '78110'
carrier_name: Aetna
location_id: '1001'
npi: null
negotiated_type: negotiated
negotiation_arrangement: ffs
min: 14200
median: 16850
avg: 17120.5
max: 21400
care_cluster_codes:
- JOINT_REPLACEMENT
'400':
description: Invalid query parameters (for example both `carrier_id` and `plan_id`).
content:
application/json:
schema:
$ref: '#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema'
'403':
description: The caller does not have Price Transparency access.
content:
application/json:
schema:
$ref: '#/paths/~1v2~1carriers/get/responses/403/content/application~1json/schema'
'404':
description: The given location could not be found.
content:
application/json:
schema:
type: object
description: The requested resource could not be found
required:
- error
properties:
error:
type: object
required:
- status
- code
- message
properties:
status:
type: integer
example: 404
code:
type: string
enum:
- not_found
message:
type: string
enum:
- resource not found
x-apievangelist-inlined-from: https://ribbon.readme.io/reference/getcustomtin.md
x-apievangelist-inline-note: Verbatim from the provider's own published OpenAPI slice for GET /v1/custom/tin/{tin_id}.
Inlined only because ReadMe's per-operation slicing left this $ref pointing outside the Price
Transparency v2 paths. Content unmodified.
'501':
description: '`plan_id` filtering is not implemented yet.'
content:
application/json:
schema:
$ref: '#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema'
/v2/locations/{location_id}/pricing/care-clusters:
get:
summary: Location Care Cluster Pricing (v2)
description: 'Return care-cluster (bundle) prices for a single facility / practice
location, optionally filtered by carrier.
Results are ordered cheapest-first by `bundle_price`.
Each record includes completeness fields so clients can see how much of the
expected procedure set has pricing at that site:
`procedure_count`, `expected_procedure_count`, `completeness_pct`,
`included_procedures`, and `missing_procedures`.
#### Path parameter
`location_id` accepts either the integer location id **or** the location UUID.
Unknown values return HTTP 404.
#### Carrier filtering
Prefer `carrier_id`. `plan_id` currently returns HTTP 501.
`carrier_id` and `plan_id` are mutually exclusive.
'
operationId: getV2LocationCareClusterPricing
tags:
- Price Transparency v2
parameters:
- $ref: '#/paths/~1v2~1locations~1%7Blocation_id%7D~1pricing~1procedures/get/parameters/0'
- $ref: '#/paths/~1v2~1pricing~1locations~1procedures/get/parameters/7'
- $ref: '#/paths/~1v2~1carriers/get/parameters/1'
- $ref: '#/paths/~1v2~1procedures/get/parameters/4'
- $ref: '#/paths/~1v2~1procedures/get/parameters/0'
- $ref: '#/paths/~1v2~1pricing~1locations~1procedures/get/parameters/9'
- $ref: '#/paths/~1v2~1carriers/get/parameters/2'
- $ref: '#/paths/~1v2~1carriers/get/parameters/3'
responses:
'200':
description: Care cluster price records for the location.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1v2~1carriers/get/responses/200/content/application~1json/schema/allOf/0'
- type: object
properties:
data:
type: array
items:
type: object
description: 'Location-scoped care-cluster (bundle) price for a single carrier.
'
required:
- care_cluster_code
- care_cluster_description
- carrier_id
- carrier_name
- location_id
- bundle_price
- procedure_count
- expected_procedure_count
- completeness_pct
- included_procedures
- missing_procedures
properties:
care_cluster_code:
type: string
example: JOINT_REPLACEMENT
care_cluster_description:
type: string
example: Joint Replacement
carrier_id:
type: string
example: '78110'
carrier_name:
type: string
example: Aetna
location_id:
type: string
description: Location id as a string.
example: '1001'
npi:
type:
- integer
- 'null'
example: null
bundle_price:
type: number
format: float
description: Aggregated price for the cluster at this location / carrier.
example: 28500
procedure_count:
type: integer
description: How many expected procedures in the cluster have pricing.
example: 4
expected_procedure_count:
type: integer
description: How many procedures the cluster definition expects.
example: 5
completeness_pct:
type: number
format: float
description: Coverage percentage (`procedure_count / expected_procedure_count`).
example: 80
included_procedures:
type: array
description: Procedures that contributed to the bundle. Defaults to `[]`.
items: {}
example:
- '27447'
- '27446'
missing_procedures:
type: array
description: Expected procedures with no price at this location/carrier. Defaults to
`[]`.
items: {}
example:
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ribbon-health/refs/heads/main/openapi/ribbon-health-price-transparency-v2-api-openapi.yml