--- updatedAt: 2026-06-05T13:06:03.000Z agentTools: projectIndex: https://ribbon.readme.io/llms.txt --- # Add Or Remove Provider Insurances At A Location Add or remove insurances accepted by a provider at a specific location using our standard insurance UUIDs. # 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 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/providers/{npi}/locations/{location_uuid}/insurances": { "put": { "summary": "Add Or Remove Provider Insurances At A Location", "description": "Add or remove insurances accepted by a provider at a specific location using our standard insurance UUIDs.\n", "operationId": "putCustomProviderLocationInsurances", "tags": [ "Providers" ], "parameters": [ { "$ref": "#/paths/~1v1~1custom~1providers~1%7Bnpi%7D/get/parameters/0" }, { "$ref": "#/paths/~1v1~1custom~1locations~1%7Blocation_uuid%7D/get/parameters/0" } ], "requestBody": { "required": true, "description": "A set of instructions for how to update the provider's insurances at this location.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v1~1custom~1providers~1%7Bnpi%7D~1locations/put/requestBody/content/application~1json/schema" } } } }, "responses": { "200": { "description": "The insurances list was successfully modified.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/paths/~1v1~1custom~1providers~1%7Bnpi%7D~1locations/put/requestBody/content/application~1json/schema" } } } } } }, "400": { "description": "This request attempted to use fields which are not supported or use items that are not valid UUIDs.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema" } } } }, "403": { "description": "Trial accounts do not have access to custom provider directories", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/403/content/application~1json/schema" } } } }, "404": { "description": "The given NPI or location UUID 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": [] } ] } ```