---
updatedAt: 2026-06-05T13:06:03.000Z
agentTools:
  projectIndex: https://ribbon.readme.io/llms.txt
---

# Provider Location Procedure Pricing

Search for a price estimate for a specific procedure from a specific provider at a specific location, with a given insurance plan.

#### Example Use Case
Given an insurance, identify the expected price of a particular procedure from a specific provider at a known facility.


# OpenAPI definition

```json
{
  "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",
      "description": "Legacy provider-first negotiated rate endpoints under `/v1/pricing/*`."
    },
    {
      "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"
    }
  ],
  "paths": {
    "/v1/custom/insurances": {
      "post": {
        "summary": "Create Insurance",
        "description": "Create a insurance with desired field values.\n",
        "operationId": "postCustomInsurance",
        "tags": [
          "Reference Endpoints"
        ],
        "requestBody": {
          "required": true,
          "description": "A JSON object mapping the name of the field to update to its new value",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "uuid": {
                    "type": "string",
                    "format": "uuid",
                    "example": "d8addf29-1054-4ccb-b179-dda65f7fefdd",
                    "description": "A UUID uniquely identifying this insurance"
                  },
                  "carrier_association": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "Aetna"
                  },
                  "carrier_brand": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "Aetna"
                  },
                  "carrier_name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "Aetna"
                  },
                  "state": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "NY"
                  },
                  "plan_name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "Aetna HealthFund Open Choice"
                  },
                  "plan_type": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "PPO"
                  },
                  "metal_level": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "display_name": {
                    "type": "string",
                    "example": "Aetna - HealthFund Open Choice - PPO"
                  },
                  "network": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "confidence": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "example": 4
                  },
                  "category": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "codes": {
                    "type": [
                      "array"
                    ],
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Insurance was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/paths/~1v1~1custom~1insurances/post/requestBody/content/application~1json/schema"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "This request attempted to update with invalid schema or was missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema"
                }
              }
            }
          },
          "409": {
            "description": "Insurance object with given fields already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1v1~1custom~1locations/post/responses/409/content/application~1json/schema"
                }
              }
            }
          }
        }
      }
    },
    "/v1/pricing/providers/{npi}/procedures/{procedure_uuid}/locations/{location_uuid}": {
      "get": {
        "summary": "Provider Location Procedure Pricing",
        "description": "Search for a price estimate for a specific procedure from a specific provider at a specific location, with a given insurance plan.\n\n#### Example Use Case\nGiven an insurance, identify the expected price of a particular procedure from a specific provider at a known facility.\n",
        "operationId": "getPricingProviderProcedureLocation",
        "tags": [
          "Price Transparency"
        ],
        "parameters": [
          {
            "$ref": "#/paths/~1v1~1custom~1providers~1%7Bnpi%7D/get/parameters/0"
          },
          {
            "$ref": "#/paths/~1v1~1pricing~1providers~1%7Bnpi%7D~1procedures~1%7Bprocedure_uuid%7D/get/parameters/1"
          },
          {
            "$ref": "#/paths/~1v1~1custom~1locations~1%7Blocation_uuid%7D/get/parameters/0"
          },
          {
            "$ref": "#/paths/~1v1~1pricing~1providers~1%7Bnpi%7D~1procedures/get/parameters/1"
          }
        ],
        "responses": {
          "200": {
            "description": "Returns the costs associated with the given provider, procedure, and location",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "parameters",
                    "data"
                  ],
                  "properties": {
                    "parameters": {
                      "properties": {
                        "insurance": {
                          "$ref": "#/paths/~1v1~1custom~1insurances/post/requestBody/content/application~1json/schema"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "costs": {
                          "type": "object",
                          "properties": {
                            "min": {
                              "type": "number",
                              "example": 239,
                              "description": "The minimum cost for this procedure in dollars"
                            },
                            "avg": {
                              "type": "number",
                              "example": 520.5350000000001,
                              "description": "The median cost for this procedure in dollars\n\nThis key is misnamed. For backwards compatibility, we have retained the legacy name.\n"
                            },
                            "max": {
                              "type": "number",
                              "example": 714.93,
                              "description": "The maximum cost for this procedure in dollars"
                            },
                            "is_bundle": {
                              "type": "boolean",
                              "example": true,
                              "description": "Where this data is the costs for a procedure bundle rather than a regular procedure."
                            },
                            "outpatient": {
                              "$ref": "#/paths/~1v1~1pricing~1providers~1%7Bnpi%7D~1procedures~1%7Bprocedure_uuid%7D~1locations~1%7Blocation_uuid%7D/get/responses/200/content/application~1json/schema/properties/data/properties/costs/properties/inpatient",
                              "description": "Costs associated with this procedure in an outpatient setting.\n\nThis key will only be populated for procedure bundles, and only if we have relevant data. A regular procedure will always have a `null` value here.\n"
                            },
                            "inpatient": {
                              "description": "Costs associated with this procedure in an inpatient setting.\n\nThis key will only be populated for procedure bundles, and only if we have relevant data. A regular procedure will always have a `null` value here.\n",
                              "type": [
                                "object",
                                "null"
                              ],
                              "required": [
                                "min",
                                "median",
                                "max",
                                "is_bundle",
                                "components"
                              ],
                              "properties": {
                                "min": {
                                  "type": "number",
                                  "example": 239,
                                  "description": "The minimum cost for this procedure in this place of service, in dollars."
                                },
                                "median": {
                                  "type": "number",
                                  "example": 520.5350000000001,
                                  "description": "The median cost for this procedure in this place of service, in dollars.\n"
                                },
                                "max": {
                                  "type": "number",
                                  "example": 714.93,
                                  "description": "The maximum cost for this procedure in this place of service, in dollars."
                                },
                                "is_bundle": {
                                  "type": "boolean",
                                  "example": true,
                                  "description": "Where this data is the costs for a procedure bundle rather than a regular procedure."
                                },
                                "components": {
                                  "type": [
                                    "array",
                                    "null"
                                  ],
                                  "description": "Individual costs for the components that make up this procedure bundle.\n\nFor a regular procedure, this field will always be `null`.\n",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "display": {
                                        "type": "string",
                                        "example": "Knee replacement surgery",
                                        "description": "The display name for this component of a procedure bundle."
                                      },
                                      "min": {
                                        "type": "number",
                                        "example": 239,
                                        "description": "The minimum cost for this component in this place of service, in dollars."
                                      },
                                      "median": {
                                        "type": "number",
                                        "example": 520.5350000000001,
                                        "description": "The median cost for this component in this place of service, in dollars.\n"
                                      },
                                      "max": {
                                        "type": "number",
                                        "example": 714.93,
                                        "description": "The maximum cost for this component in this place of service, in dollars."
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The given search was not valid. The given insurance could not be found, etc.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema"
                }
              }
            }
          },
          "404": {
            "description": "The given NPI cannot be found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1v1~1custom~1tin~1%7Btin_id%7D/get/responses/404/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"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
```