--- updatedAt: 2026-06-05T13:06:03.000Z agentTools: projectIndex: https://ribbon.readme.io/llms.txt --- # Search Locations Allows you to search for different service locations, including specific location types. # 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/locations": { "get": { "summary": "Search Locations", "description": "Allows you to search for different service locations, including specific location types.\n", "operationId": "getCustomLocations", "tags": [ "Locations" ], "parameters": [ { "name": "Pagination and Search Configuration Options", "in": "query", "required": false, "description": "Options to control what data gets returned to you.", "explode": true, "schema": { "type": "object", "properties": { "page": { "type": "integer", "example": 1, "description": "The page of the results which was returned." }, "page_size": { "type": "integer", "example": 25, "description": "How many results are in each page." }, "fields": { "type": "string", "example": "name,address", "description": "Comma separated list of fields within the location object to return. Can be used to greatly reduce the size of the response by requesting only data you intend to use.\nCannot be used in tandem with `_excl_fields`\n" }, "_excl_fields": { "type": "string", "example": "phone_numbers,insurances", "description": "Comma separated list of fields within the location object to exclude from the response. Can be used to greatly reduce the size of the response by requesting only data you intend to use." } } } }, { "name": "Location Search Options", "in": "query", "required": false, "description": "Search options based on aspects of the location objects.", "explode": true, "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "String input of an address that will be interpreted and geocoded in real time.", "example": "New York, NY" }, "name": { "type": "string", "description": "String input for a 'fuzzy' search on location name.", "example": "Citymd Urgent Care" }, "distance": { "type": "integer", "example": 10, "description": "The proximity radius of locations returned.\n" }, "location_types": { "type": "string", "description": "Comma separated list of values that filter to what type of facilities to show. We categorize locations into 36 types. Clients can add their own locations with unique location_types, and they will also be included in the search.\nSee the Location Types Reference Endpoint for a list of all location types.\n", "example": "Urgent Care" }, "_excl_location_types": { "type": "string", "description": "Comma separated list of the 'types' of locations to exclude. Excludes locations with a matching location type.\n", "example": "Urgent Care" }, "location": { "type": "string", "description": "Latitude/longitude pair of coordinates in lieu of a string address.", "example": "37.7489816,-122.4802092" }, "location_ids": { "type": "string", "description": "Comma separated list of desired practice location uuids.", "example": "48d4eb27-d82b-4ea4-8ad0-4bcb2c46a960" }, "_excl_location_ids": { "type": "string", "description": "Comma separated list of practice location uuids to exclude.", "example": "48d4eb27-d82b-4ea4-8ad0-4bcb2c46a960" }, "insurance_ids": { "type": "string", "description": "Comma separated list of desired insurance uuids. See all locations that accept a given insurance(s).", "example": "24617022-92b3-4b9f-af1c-4df21ad6fb6f" }, "_excl_insurance_ids": { "type": "string", "description": "Comma separated list of insurance uuids to exclude. Exclude locations that accept a given insurance(s).", "example": "24617022-92b3-4b9f-af1c-4df21ad6fb6f" }, "insurance_carrier_name": { "type": "string", "description": "String input of carrier_name in order to search for all locations that take at least one plan from a given insurance carrier.\nFind the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.\nNote: This input must be an exact string match to work\n", "example": "Aetna" }, "min_confidence": { "type": "integer", "minimum": 0, "maximum": 5, "description": "Integer input (0-5) of the minimum confidence threshold for returned locations. min_location_confidence=4 will only display locations that have a confidence 4 or higher.\n" }, "national_bluecard": { "type": "boolean", "example": true, "description": "Boolean input that enables an API search to automatically default to the National BlueCard EPO/PPO Network whenever a member searches for out-of-state, in-network care and is covered by a BCBS Association PPO insurance plan. Use the parameter in conjunction with the address parameter and either the insurance_ids or insurance fuzzy search parameters. Defaults to true unless otherwise specified." }, "ultimate_parent_id": { "type": "string", "description": "Exact match on the ultimate parent organization ID. Filters to only locations that have the given ultimate parent ID.\n", "example": "12345" }, "ultimate_parent_name": { "type": "string", "description": "Fuzzy prefix search on the ultimate parent organization name. Returns locations with an ultimate parent name matching the given prefix.\n", "example": "Acme Health" }, "tier": { "type": "integer", "enum": [ 1, 2, 3 ], "example": 1, "description": "Filter to locations with the given quality tier derived from the linked organization's `hco_research` flags.\n\n * `1` - High-confidence facility\n * `2` - Medium-confidence facility\n * `3` - Low-confidence facility\n\nOnly `1`, `2`, or `3` are accepted; any other value returns a 400. Locations whose `tier` is `null` in the index are excluded from the result set when this parameter is set.\n" } } } }, { "name": "Organization Search Criteria", "in": "query", "required": false, "description": "Criteria used to search for locations based on the organizations they belong to.", "explode": true, "schema": { "type": "object", "properties": { "organization_ids": { "type": "string", "description": "Comma separated list of desired organization uuids. Filters to only locations that are affiliated with the given organization uuid(s).\n", "example": "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" }, "_excl_organization_ids": { "type": "string", "description": "Comma separated list of organization uuids to exclude. Excludes locations that are affiliated with the given organization uuid(s).", "example": "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" } } } }, { "name": "Focus Area Search Criteria", "in": "query", "required": false, "description": "Criteria used to search for locations based on their Focus Areas.", "explode": true, "schema": { "type": "object", "properties": { "clinical_area": { "type": "string", "description": "String input that is fuzzy matched to the most relevant `clinical_area.display` field. Only a single clinical area will be selected.\nReturns all location with this clinical area.\n", "example": "CT" }, "clinical_area_ids": { "type": "string", "description": "Comma-separated list of desired clinical area ids.\nReturns all locations with a clinical area exactly matching any of the entered IDs.\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n", "example": "4c03ddb4-f6c0-4574-a51e-508f83c43d69" }, "_excl_clinical_area_ids": { "type": "string", "description": "Comma-separated list of clinical area ids to exclude.\nReturns all locations without a clinical area exactly matching any of the entered IDs.\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n", "example": "4c03ddb4-f6c0-4574-a51e-508f83c43d69" }, "treatment": { "type": "string", "description": "String input that is fuzzy matched to the most relevant `treatments.display` field. Only a single treatment will be selected.\nReturns all locations with this treatment.\n", "example": "Neck X-ray" }, "treatment_ids": { "type": "string", "description": "Comma-separated list of desired treatment ids.\nReturns all locations with a `treatments.uuid` field exactly matching any of the entered IDs.\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n", "example": "e3079513-bf55-41cc-87c6-f7ff5f923085" }, "_excl_treatment_ids": { "type": "string", "description": "Comma-separated list of treatment ids to exclude.\nReturns all locations without a `treatments.uuid` field exactly matching any of the entered IDs.\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n", "example": "e3079513-bf55-41cc-87c6-f7ff5f923085" } } } }, { "name": "TINs Search Criteria", "in": "query", "required": false, "description": "Criteria used to search for locations based on the TINs they are associated with.", "explode": true, "schema": { "type": "object", "properties": { "tin_ids": { "type": "string", "description": "Comma separated list of desired TINs. Filters to only locations that are affiliated with the given TINs.\nNote: This parameter cannot be used in combination with any other TINs related parameters. All other TINs related parameters will be ignored.\n" }, "tin_name": { "type": "string", "description": "String input that is fuzzy matched against the `tins.name` field. Filters to only locations that are affiliated with the given TINs name." }, "tin_legal_name": { "type": "string", "description": "String input that is fuzzy matched against the `tins.legal_name` field. Filters to only locations that are affiliated with the given TINs legal name." } } } } ], "responses": { "200": { "description": "Returns an ordered list of matching locations", "content": { "application/json": { "schema": { "type": "object", "required": [ "parameters", "data" ], "properties": { "parameters": { "allOf": [ { "type": "object", "properties": { "total_count": { "type": "integer", "example": 141, "description": "The total number of results matched, across all pages." }, "sort_by": { "type": "string", "example": "distance", "description": "The main criteria used to sort results in the record set." }, "geo": { "type": "object", "properties": { "latitude": { "type": "number", "example": 40.7351327, "description": "The latitude the search was focused on." }, "longitude": { "type": "number", "example": -73.9881657, "description": "The longitude the search was focused on." } } } } }, { "type": "object", "properties": { "page": { "type": "integer", "example": 1, "description": "The page of the results which was returned." }, "page_size": { "type": "integer", "example": 25, "description": "How many results are in each page." }, "fields": { "type": "array", "items": { "type": "string", "example": "locations" }, "example": [ "locations", "age" ], "description": "List of fields within the location object to return. Can be used to greatly reduce the size of the response by requesting only data you intend to use.\n\nCannot be used in tandem with `_excl_fields`\n" }, "_excl_fields": { "type": "array", "items": { "type": "string", "example": "locations" }, "example": [ "locations", "age" ], "description": "List of fields within the location object to exclude from the response. Can be used to greatly reduce the size of the response by requesting only data you intend to use." } } }, { "type": "object", "properties": { "address": { "type": "string", "description": "String input of an address that will be interpreted and geocoded in real time.", "example": "New York, NY" }, "name": { "type": "string", "description": "String input for a fuzzy search on location name.", "example": "Citymd Urgent Care" }, "distance": { "type": "integer", "example": 10, "description": "The proximity radius of locations returned.\n" }, "location_types": { "type": "array", "items": { "type": "string", "example": "Urgent Care" }, "description": "List of values that filter to what type of facilities to show. We categorize locations into 34 types. Clients can add their own locations with unique location_types, and they will also be included in the search.\nSee the Location Types Reference Endpoint for a list of all location types.\n", "example": [ "Urgent Care" ] }, "_excl_location_types": { "type": "array", "items": { "type": "string", "example": "Urgent Care" }, "description": "List of the 'types' of locations to exclude. Excludes locations with a matching location type.\n", "example": [ "Urgent Care" ] }, "insurance_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652" }, "description": "List of desired insurance uuids. See all locations that accept a given insurance(s).", "example": [ "e527f6e3-fe42-4932-bf34-d81f1c1fd652" ] }, "_excl_insurance_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "e527f6e3-fe42-4932-bf34-d81f1c1fd652" }, "description": "List of insurance uuids to exclude. Exclude locations that accept a given insurance(s).", "example": [ "e527f6e3-fe42-4932-bf34-d81f1c1fd652" ] }, "insurance_carrier_name": { "type": "string", "description": "String input of carrier_name in order to search for all locations that take at least one plan from a given insurance carrier.\nFind the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.\nNote: This input must be an exact string match to work\n", "example": "Aetna" }, "min_confidence": { "type": "integer", "minimum": 0, "maximum": 5, "description": "Integer input (0-5) of the minimum confidence threshold for returned locations. min_location_confidence=4 will only display locations that have a confidence 4 or higher.\n" }, "national_bluecard": { "type": "boolean", "example": true, "description": "Boolean input that enables an API search to automatically default to the National BlueCard EPO/PPO Network whenever a member searches for out-of-state, in-network care and is covered by a BCBS Association PPO insurance plan. Use the parameter in conjunction with the address parameter and either the insurance_ids or insurance fuzzy search parameters. Defaults to true unless otherwise specified." }, "tier": { "type": "integer", "enum": [ 1, 2, 3 ], "example": 1, "description": "Filter to locations with the given quality tier (`1` = high, `2` = medium, `3` = low). Locations with `tier = null` are excluded when this filter is set.\n" } } }, { "type": "object", "properties": { "organization_ids": { "type": "array", "items": { "type": "string", "example": "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" }, "description": "Comma separated list of desired organization uuids. Filters to only locations that are affiliated with the given organization uuid(s).\n", "example": [ "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" ] }, "_excl_organization_ids": { "type": "array", "items": { "type": "string", "example": "497a1ac1-52cc-43a9-b796-844dabde10fc" }, "description": "Comma separated list of organization uuids to exclude. Excludes locations that are affiliated with the given organization uuid(s).", "example": [ "86722ebb-1dd1-4846-a1a9-a7a9e36c944d" ] } } }, { "type": "object", "properties": { "clinical_area": { "$ref": "#/paths/~1v1~1custom~1clinical_areas~1%7Bclinical_area_uuid%7D/get/responses/200/content/application~1json/schema" }, "clinical_area_ids": { "type": "array", "items": { "type": "string", "example": "4c03ddb4-f6c0-4574-a51e-508f83c43d69" }, "description": "List of desired clinical area ids.\nReturns all locations with a clinical area exactly matching any of the entered IDs.\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)\n", "example": [ "4c03ddb4-f6c0-4574-a51e-508f83c43d69" ] }, "treatment": { "$ref": "#/paths/~1v1~1custom~1treatments~1%7Btreatment_uuid%7D/get/responses/200/content/application~1json/schema" }, "treatment_ids": { "type": "array", "items": { "type": "string", "example": "e3079513-bf55-41cc-87c6-f7ff5f923085" }, "description": "List of desired treatment ids.\nReturns all providers with a `treatments.uuid` field exactly matching any of the entered IDs.\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)\n", "example": [ "e3079513-bf55-41cc-87c6-f7ff5f923085" ] } } }, { "type": "object", "properties": { "tin_ids": { "type": "string", "description": "List of desired TINs." }, "tin_name": { "type": "string" }, "tin_legal_name": { "type": "string" } } } ] }, "data": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "distance": { "type": "number", "example": 0.4, "description": "This location's distance from the center of a geographic search, in miles." } } }, { "$ref": "#/paths/~1v1~1custom~1locations~1%7Blocation_uuid%7D/get/responses/200/content/application~1json/schema" } ] } } } } } } }, "400": { "description": "The search could not be completed as requested", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema" } } } }, "403": { "description": "Account does not have access to custom locations directory", "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" } } } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ] } ```