--- updatedAt: 2026-06-05T13:06:03.000Z agentTools: projectIndex: https://ribbon.readme.io/llms.txt --- # Get Location Retrieve data on a specific location. # 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" } ], "paths": { "/v1/custom/locations/{location_uuid}": { "get": { "summary": "Get Location", "description": "Retrieve data on a specific location.\n", "operationId": "getCustomLocation", "tags": [ "Locations" ], "parameters": [ { "name": "location_uuid", "in": "path", "required": true, "description": "The UUID of the target location.", "schema": { "type": "string", "format": "uuid", "example": "34ecc98a-e49e-49e3-84f9-b0ab2ff00495" } } ], "responses": { "200": { "description": "Returns a single location", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "f38b9fd5-1e28-4f6e-953c-1e1493b68e21", "description": "A UUID uniquely identifying this location" }, "name": { "type": [ "string", "null" ] }, "address": { "type": "string", "example": "185 Berry St # 130, San Francisco, CA 94107, US" }, "address_details": { "type": "object", "properties": { "street": { "type": "string", "example": "185 Berry St # 130" }, "address_line_1": { "type": "string", "example": "185 Berry St" }, "address_line_2": { "type": [ "string", "null" ], "example": "# 130" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": 94107 }, "zip_suffix": { "type": [ "string", "null" ], "example": 1234 } } }, "latitude": { "type": "number", "example": 37.7765973 }, "longitude": { "type": "number", "example": -122.3919488 }, "google_maps_link": { "type": "string", "format": "url", "example": "https://www.google.com/maps/@37.7765973-122.3919488?q=185%20Berry%20St%20%23%20130%2C%20SF%2C%20CA%2094107%2C%20US" }, "phone_numbers": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string", "example": 4155146410 }, "details": { "type": "string", "example": "primary" } } } }, "faxes": { "type": "array", "description": "Fax numbers associated with this location.\n\nThis property only appears for customers purchasing fax data. If you would like this property and are not receiving it, please reach out to support.\n", "items": { "type": "object", "properties": { "fax": { "type": "string", "example": 2121234567 }, "details": { "type": "string", "example": "secondary" }, "confidence": { "type": "integer", "example": 3, "description": "Note, this is a premium field and may not be enabled in your API index. Please reach out to H1 Support (support@h1.co) for additional information" } } } }, "confidence": { "type": [ "integer", "null" ], "example": 2, "description": "Each location contains a confidence score. This score indicates the probability of the given provider practicing at said location with the included contact information\n\nThis field will only be populated for Ribbon-provided locations. Locations you create yourself will have a confidence score of `null`.\n" }, "tier": { "type": [ "integer", "null" ], "enum": [ 1, 2, 3, null ], "example": 1, "description": "Quality tier of the location, derived from the linked organization's hco_research flags.\n\n * `1` - High-confidence facility (linked org has `hco_research_high = true`)\n * `2` - Medium-confidence facility (linked org has `hco_research_medium = true`)\n * `3` - Low-confidence facility (linked org has `hco_research_low = true`)\n * `null` - Tier could not be derived because none of the hco_research flags are true, the location has no linked organization, or it is linked to multiple organizations.\n\nLocations with `tier = null` are excluded when filtering with the `tier` query parameter.\n" }, "insurances": { "type": "array", "items": { "$ref": "#/paths/~1v1~1custom~1insurances/post/requestBody/content/application~1json/schema" }, "description": "List of insurances the accepted at this location" }, "tins": { "type": "array", "items": { "type": "string" }, "description": "Array of strings of standard 9-digit identification code(s) used by the IRS for business entities and used for contracting and paying provider/facility claims.\n" }, "npis": { "type": "array", "items": { "type": "string" }, "description": "Array of NPI numbers associated with this location." }, "provider_count": { "type": "integer", "example": 12, "description": "Number of unique providers (by NPI) associated with this location." }, "location_types": { "type": "array", "items": { "type": "string" }, "description": "Array of location types associated with this location." }, "ultimate_parent": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "5401", "description": "The ID of the ultimate parent organization" }, "name": { "type": "string", "example": "Mount Sinai Health System", "description": "The name of the ultimate parent organization" } }, "description": "The ultimate parent organization of this location, if any" } } } } } }, "404": { "description": "The given 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" } } } } } } }, "/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" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ] } ```