H1 Price Transparency v2 API

Location-first negotiated-rate API under /v2/* - resolve procedures, care clusters and carriers, then shop procedure-level and care-cluster (bundle) prices at a known facility or near an address / lat-lng, returned cheapest-first in a single shared response envelope. Separate from, and preferred over, the legacy provider-first /v1/pricing/* endpoints; gated on the doctors.can_price_transparency account entitlement.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.1.0",
  "info": {
    "title": "H1's API",
    "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"
  },
  "servers": [
    {
      "url": "https://api.ribbonhealth.com"
    }
  ],
  "tags": [
    {
      "name": "Price Transparency v2",
      "description": "Location-first negotiated rates under `/v2/*`. Prefer these endpoints for new\nintegrations. Carrier ids come from `GET /v2/carriers` and are not interchangeable\nwith v1 pricing carrier UUIDs. Provider-scoped v2 routes are not live yet.\n"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "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`).\n",
            "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\ndictionary endpoints; case-insensitive exact match on DB-backed pricing\nendpoints; case-sensitive exact match on Elasticsearch search endpoints.\n",
            "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.\n",
                                "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.\n\nA care cluster is a curated group of related procedures that together\nrepresent a care episode (for example joint replacement). Use this\ndictionary before querying bundle prices.\n\n#### Example Use Case\nSearch for clusters matching `\"joint\"` to find `JOINT_REPLACEMENT` and see\nwhich CPT codes are expected in that bundle.\n",
        "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.\n\nUse this to discover valid `carrier_id` values for pricing filters.\n\n#### Important\nThese identifiers are **not** the same as v1 [`/v1/pricing/carriers`](./getpricingcarriers)\nUUIDs. Always resolve carriers through this endpoint (or a curated customer\nmapping) when working with v2.\n",
        "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\n`/v2/carriers`; case-insensitive exact match on DB-backed pricing endpoints;\ncase-sensitive exact match on Elasticsearch search endpoints.\n",
            "schema": {
              "type": "string",
              "example": "Aetna"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page of results to return. Values below `1` are treated as `1`.\n",
            "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**.\n",
            "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.\nPagination fields are always present; `parameters` echoes the non-null filters\nthat were applied (pagination keys are omitted from the echo).\n",
                      "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.\nUse `carrier_id` as the filter value on pricing endpoints.\n",
                            "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.\n",
                          "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 /\npractice location, optionally filtered by carrier.\n\nResults are ordered cheapest-first by `min`.\n\n#### Example Use Case\nGiven location `1001` and carrier `78110`, list every procedure priced at\nthat site for that carrier, sorted from lowest to highest `min`.\n\n#### Path parameter\n`location_id` accepts either the integer location id **or** the location UUID.\nUnknown values return HTTP 404.\n\n#### Carrier filtering\nPrefer `carrier_id` (from [`GET /v2/carriers`](./getv2carriers)).\n`plan_id` is accepted in the contract but currently returns HTTP 501.\n`carrier_id` and `plan_id` are mutually exclusive (HTTP 400 if both are sent).\n",
        "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.\n",
            "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.\n",
                            "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",
                   

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/h1/refs/heads/main/openapi/h1-price-transparency-v2-openapi.json
H1 Price Transparency v2 API

Documentation

Specifications

Other Resources

OpenAPI Specification
