--- updatedAt: 2026-06-05T13:06:03.000Z agentTools: projectIndex: https://ribbon.readme.io/llms.txt --- # Get Provider Retrieve detailed information for any provider given their NPI, such as locations, contact information, education, patient satisfaction, etc. # 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": "Providers", "description": "Search and manage provider data, keyed by NPI." }, { "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}": { "get": { "summary": "Get Provider", "description": "Retrieve detailed information for any provider given their NPI, such as locations, contact information, education, patient satisfaction, etc.\n", "operationId": "getCustomProvider", "tags": [ "Providers" ], "parameters": [ { "name": "npi", "in": "path", "required": true, "description": "The 10-digit National Provider Identifier (NPI) of the healthcare provider to fetch.", "schema": { "type": "string", "pattern": "^\\d{10}$", "example": "1861664294" } }, { "name": "max_insurances", "in": "query", "required": false, "description": "If provided, returns only up to this many insurances per location. Useful to limit the amount of data returned when you do not need the entire list of accepted insurances.", "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Returns a single provider", "content": { "application/json": { "schema": { "type": "object", "properties": { "npi": { "type": "string", "pattern": "^\\d{10}$", "example": "1861664294", "description": "The healthcare provider's 10-digit National Provider Identifier (NPI)" }, "h1_person_id": { "type": [ "integer", "null" ], "example": 3530835, "description": "The H1 person ID" }, "first_name": { "type": "string", "example": "Jane", "description": "First name of the provider" }, "middle_name": { "type": [ "string", "null" ], "example": "J", "description": "Middle name of the provider" }, "last_name": { "type": "string", "example": "Doe", "description": "Last name of the provider" }, "provider_email": { "type": [ "array", "null" ], "items": { "type": "string", "format": "email", "example": "jane.doe@example.com" }, "description": "List of work email addresses associated with the provider" }, "profile_picture": { "type": [ "string", "null" ], "format": "uri", "example": "https://assets.h1insights.com/KOL Photos/image.jpg", "description": "URL of the provider's profile picture" }, "age": { "type": [ "integer", "null" ], "example": 38, "description": "The estimated age of the provider" }, "date_of_birth": { "type": [ "string", "null" ], "format": "date", "example": "1985-04-23", "description": "The provider's date of birth as an ISO-format (YYYY-MM-DD) date string. Only returned for provider directories that have been configured to include it; `null` when it is not available." }, "gender": { "type": "string", "enum": [ "m", "f" ], "description": "The gender of the provider" }, "ratings_count": { "type": "integer", "example": 20, "description": "Total number of ratings collected across different sources" }, "ratings_avg": { "type": [ "number", "null" ], "example": 9.8, "description": "Average patient satisfaction rating out of 10 points across multiple sources" }, "degrees": { "type": "array", "items": { "type": "string", "example": "MD" }, "description": "Lists all degrees associated with this provider (e.g. MD, OD, PhD)" }, "specialties": { "type": "array", "items": { "$ref": "#/paths/~1v1~1custom~1specialties~1%7Bspecialty_uuid%7D/get/responses/200/content/application~1json/schema" }, "description": "This lists all the specialties for a given provider" }, "languages": { "type": "array", "items": { "type": "string", "example": "english" }, "description": "List of confirmed languages spoken" }, "educations": { "type": "array", "items": { "type": "object", "required": [ "education", "type", "year" ], "properties": { "education": { "type": "object", "properties": { "name": { "type": "string", "example": "Stritch School of Medicine" }, "uuid": { "type": "string", "format": "uuid", "example": "0b26c31a-d74a-4327-9702-57753b82a126" } } }, "type": { "type": [ "string", "null" ] }, "year": { "type": [ "integer", "null" ], "example": 2007 } } }, "description": "List of the schools attended by the provider" }, "network_summary": { "type": "object", "description": "A lightweight summary of the provider's insurance network. Replaces the deprecated top-level `insurances` array: it gives the total count of the provider's full (uncapped) insurance set, a link to retrieve the full paginated list, and — when the request includes insurance search criteria — the matched insurance(s) that explain why the provider was returned.", "required": [ "total_insurances", "href", "matched_insurances" ], "properties": { "total_insurances": { "type": "integer", "example": 2134, "description": "Count of all known insurance relationships for this provider, from the full unfiltered dataset." }, "href": { "type": "string", "example": "/v1/custom/providers/1234567890/insurances", "description": "Link to the paginated endpoint returning the provider's full, unfiltered insurance list." }, "matched_insurances": { "type": "array", "items": { "$ref": "#/paths/~1v1~1custom~1insurances/post/requestBody/content/application~1json/schema" }, "description": "The insurance object(s) that matched the request's insurance search criteria (e.g. `insurance_ids`). Empty when no insurance search criteria were provided." } } }, "insurances": { "type": "array", "items": { "$ref": "#/paths/~1v1~1custom~1insurances/post/requestBody/content/application~1json/schema" }, "description": "(Deprecated) List of insurances the provider accepts. Use `network_summary` and the paginated `/insurances` endpoint instead.", "deprecated": true }, "provider_types": { "type": "array", "items": { "type": "string", "example": "Doctor" }, "description": "There are high level classifications for different provider types -- e.g. \"Doctor\", \"Optometry\", \"Dental Providers\", \"Nursing\", etc." }, "locations": { "type": "array", "items": { "allOf": [ { "$ref": "#/paths/~1v1~1custom~1locations~1%7Blocation_uuid%7D/get/responses/200/content/application~1json/schema" }, { "type": "object", "properties": { "accepting_new_patients": { "type": [ "string", "null" ], "example": "Y", "description": "Indicates whether the provider is likely accepting new patients at this location" } } } ] }, "description": "List of all locations this provider is known to practice at including any known phone numbers at these locations" }, "online_profiles": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" } } }, "description": "We aggregate profiles across a variety of different online sources, including booking platforms" }, "organizations": { "type": [ "array", "null" ], "items": { "$ref": "#/paths/~1v1~1custom~1organizations~1%7Borganization_uuid%7D/get/responses/200/content/application~1json/schema" }, "description": "List of all organizations this provider is known to be affiliated with. 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" }, "panel_demographics": { "type": [ "object", "null" ], "properties": { "ages": { "type": "array", "items": { "type": "string" } }, "sexes": { "type": "string" } }, "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" }, "clinical_areas": { "type": [ "array", "null" ], "items": { "$ref": "#/paths/~1v1~1custom~1clinical_areas~1%7Bclinical_area_uuid%7D/get/responses/200/content/application~1json/schema" }, "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" }, "conditions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "display": { "type": "string" } } }, "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" }, "treatments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "display": { "type": "string" } } }, "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" }, "procedures": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "display": { "type": "string" }, "cost": { "type": "object", "properties": { "cost_index": { "type": [ "number", "null" ] } } }, "quality": { "type": "object", "properties": { "experience_index": { "type": [ "number", "null" ] } } } } }, "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" }, "performance": { "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", "type": "object", "properties": { "aggregate": { "type": "object", "properties": { "cost": { "type": "object", "properties": { "efficiency_index": { "type": "number" } } }, "quality": { "type": "object", "properties": { "outcomes_index": { "type": "number" } } } } } } }, "board_certifications": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "board": { "type": "string" }, "source": { "type": "string" }, "end_date": { "type": "string" }, "start_date": { "type": "string" }, "specialty_taxonomy_code": { "type": "string" } } }, "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" }, "state_licenses": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Name on the license" }, "type": { "type": [ "string", "null" ], "description": "Type of license" }, "number": { "type": [ "string", "null" ], "description": "License number" }, "state": { "type": [ "string", "null" ], "description": "State where the license was issued" }, "country_raw": { "type": [ "string", "null" ], "description": "Raw country name" }, "country_code": { "type": [ "string", "null" ], "description": "Country code" }, "valid_from": { "type": [ "string", "null" ], "description": "Date the license is valid from" }, "valid_to": { "type": [ "string", "null" ], "description": "Date the license is valid to" }, "renewal_date": { "type": [ "string", "null" ], "description": "Date the license is up for renewal" }, "is_active": { "type": [ "string", "null" ], "description": "Whether the license is currently active" } } }, "description": "List of state licenses held by this provider" } } } } } }, "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 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" } } } } } } }, "/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": [] } ] } ```