Ribbon Health · Schema
getPricingProviders
JSON Schema for getPricingProviders response from Ribbon Health H1 API
HealthcareProvider DirectoryInsuranceClinical DataCare NavigationEligibilityPrice TransparencyProvider SearchHealth PlansDigital Health
Properties
| Name | Type | Description |
|---|---|---|
| parameters | object | |
| data | array | All of the metadata on a specific provider plus a `matched_location` key showing the costs at the least expensive location. |
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "getPricingProviders",
"description": "JSON Schema for getPricingProviders response from Ribbon Health H1 API",
"required": [
"data",
"parameters"
],
"type": "object",
"properties": {
"parameters": {
"type": "object",
"properties": {
"total_count": {
"type": "integer",
"description": "The total number of results matched, across all pages.",
"format": "int32",
"example": 141
},
"page": {
"type": "integer",
"description": "The page of the results which was returned.",
"format": "int32",
"example": 1
},
"page_size": {
"type": "integer",
"description": "How many results are in each page.",
"format": "int32",
"example": 25
},
"procedure_id": {
"type": "string",
"description": "The UUID of the procedure that results were filtered to.\n\nOnly populated when the `procedure_id` search parameter was used.",
"format": "uuid",
"example": "7ad7c4ef-baf9-4789-8e58-51d2308a1143"
},
"procedure": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A UUID uniquely identifying this procedure",
"format": "uuid",
"example": "0a9a245f-2f52-4cc0-a5c3-77a811acc6f7"
},
"display": {
"type": "string",
"example": "MRI, arm"
},
"procedure_code_count": {
"type": "integer",
"format": "int32",
"example": 7
},
"procedure_codes": {
"type": "array",
"description": "",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "73222"
},
"type": {
"type": "string",
"example": "CPT"
},
"description": {
"type": "string",
"example": "MRI, arm"
}
}
}
}
}
},
"insurances": {
"type": "array",
"description": "List of insurance UUIDs for this provider.",
"items": {
"type": "string",
"format": "uuid"
}
},
"insurance": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A UUID uniquely identifying this insurance",
"format": "uuid",
"example": "d8addf29-1054-4ccb-b179-dda65f7fefdd"
},
"plan_name": {
"type": "string",
"nullable": true,
"example": "Aetna HealthFund Open Choice"
},
"carrier_name": {
"type": "string",
"nullable": true,
"example": "Aetna"
}
}
},
"specialty_ids": {
"type": "array",
"description": "A comma separated list of specialty UUIDs. Filter to providers with any of the given specialties.",
"example": [
"fcc9a22c-7a0f-4405-b0c9-c5f8ad83b93e",
"8b5d3998-d7e2-4b9e-91d1-17c19cd089f5",
"44b0284c-f360-4312-a17d-d601651cb0ea"
],
"items": {
"type": "string",
"format": "uuid"
}
},
"specialty": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A UUID uniquely identifying this specialty",
"format": "uuid",
"example": "18d8ad26-7e5f-44ac-9afa-966efb375344"
},
"taxonomy_code": {
"example": "207Q00000X",
"oneOf": [
{
"type": "string"
}
]
},
"board_specialty": {
"type": "string",
"nullable": true,
"example": "Family Medicine"
},
"board_sub_specialty": {
"type": "string",
"nullable": true
},
"non_md_specialty": {
"type": "string",
"nullable": true
},
"non_md_sub_specialty": {
"type": "string",
"nullable": true,
"example": "None"
},
"provider_name": {
"type": "string",
"nullable": true,
"example": "Family Medicine Doctor"
},
"colloquial": {
"type": "string",
"nullable": true
},
"taxonomy_1": {
"type": "string",
"nullable": true,
"example": "Allopathic & Osteopathic Physicians"
},
"taxonomy_2": {
"type": "string",
"nullable": true,
"example": "Family Medicine"
},
"taxonomy_3": {
"type": "string",
"nullable": true
},
"display": {
"type": "string",
"example": "Family Medicine"
},
"provider_type": {
"type": "string",
"example": "Doctor"
},
"is_primary": {
"type": "boolean",
"description": "Whether or not a specialty is a provider's primary specialty",
"example": true
}
}
},
"address": {
"type": "string",
"description": "String input of an address that will be interpreted and geocoded in real time.",
"example": "2074 23rd Ave, San Francisco, CA 94116"
},
"location": {
"type": "string",
"description": "Latitude/longitude pair of coordinates in lieu of a string address.",
"example": "37.7489816,-122.4802092"
},
"distance": {
"type": "integer",
"description": "The proximity radius of providers returned.",
"format": "int32",
"example": 10
},
"fields": {
"type": "array",
"description": "List of fields within the provider object to return. Can be used to greatly reduce the size of the response by requesting only data you intend to use.\n\nNote that all price information is nested under the `matched_location` field. You almost certainly want to return this field.\n\nCannot be used in tandem with `_excl_fields`",
"example": [
"matched_location",
"npi"
],
"items": {
"type": "string"
}
},
"_excl_fields": {
"type": "array",
"description": "List of fields within the provider 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.\n\nCannot be used in tandem with `fields`",
"example": [
"insurances",
"age"
],
"items": {
"type": "string"
}
}
}
},
"data": {
"type": "array",
"description": "All of the metadata on a specific provider plus a `matched_location` key showing the costs at the least expensive location.",
"items": {
"type": "object",
"properties": {
"insurance": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the insurance these prices correspond to.",
"format": "uuid",
"example": "ef704f14-c906-4857-acd4-d811f1394c32"
},
"plan_name": {
"type": "string",
"description": "The name of the insurance plan this UUID represents.",
"example": "Aetna"
},
"carrier_name": {
"type": "string",
"description": "The carrier that this insurance plan is associated with, if any.",
"nullable": true
}
}
},
"procedure": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "The UUID of the procedure these prices correspond to.",
"format": "uuid",
"example": "7ad7c4ef-baf9-4789-8e58-51d2308a1143"
},
"name": {
"type": "string",
"description": "The name of the procedure these prices correspond to.",
"example": "MRI, leg"
}
}
},
"matched_location": {
"type": "object",
"properties": {
"costs": {
"type": "object",
"properties": {
"min": {
"type": "string",
"description": "The minimum cost for this procedure in dollars",
"example": "239.0"
},
"median": {
"type": "string",
"description": "The median cost for this procedure in dollars",
"example": "520.5350000000001"
},
"max": {
"type": "string",
"description": "The maximum cost for this procedure in dollars",
"example": "714.93"
},
"is_bundle": {
"type": "boolean",
"description": "Where this data is the costs for a procedure bundle rather than a regular procedure.",
"example": true
},
"outpatient": {
"oneOf": [
{
"nullable": true
},
{
"required": [
"components",
"is_bundle",
"max",
"median",
"min"
],
"type": "object",
"properties": {
"min": {
"type": "number",
"description": "The minimum cost for this procedure in this place of service, in dollars.",
"example": 239
},
"median": {
"type": "number",
"description": "The median cost for this procedure in this place of service, in dollars.",
"example": 520.535
},
"max": {
"type": "number",
"description": "The maximum cost for this procedure in this place of service, in dollars.",
"example": 714.93
},
"is_bundle": {
"type": "boolean",
"description": "Where this data is the costs for a procedure bundle rather than a regular procedure.",
"example": true
},
"components": {
"type": "array",
"description": "Individual costs for the components that make up this procedure bundle.\n\nFor a regular procedure, this field will always be `null`.",
"nullable": true,
"items": {
"type": "object",
"properties": {
"display": {
"type": "string",
"description": "The display name for this component of a procedure bundle.",
"example": "Knee replacement surgery"
},
"min": {
"type": "number",
"description": "The minimum cost for this component in this place of service, in dollars.",
"example": 239
},
"median": {
"type": "number",
"description": "The median cost for this component in this place of service, in dollars.",
"example": 520.535
},
"max": {
"type": "number",
"description": "The maximum cost for this component in this place of service, in dollars.",
"example": 714.93
}
}
}
}
},
"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."
}
],
"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."
},
"inpatient": {
"oneOf": [
{
"nullable": true
},
{
"required": [
"components",
"is_bundle",
"max",
"median",
"min"
],
"type": "object",
"properties": {
"min": {
"type": "number",
"description": "The minimum cost for this procedure in this place of service, in dollars.",
"example": 239
},
"median": {
"type": "number",
"description": "The median cost for this procedure in this place of service, in dollars.",
"example": 520.535
},
"max": {
"type": "number",
"description": "The maximum cost for this procedure in this place of service, in dollars.",
"example": 714.93
},
"is_bundle": {
"type": "boolean",
"description": "Where this data is the costs for a procedure bundle rather than a regular procedure.",
"example": true
},
"components": {
"type": "array",
"description": "Individual costs for the components that make up this procedure bundle.\n\nFor a regular procedure, this field will always be `null`.",
"nullable": true,
"items": {
"type": "object",
"properties": {
"display": {
"type": "string",
"description": "The display name for this component of a procedure bundle.",
"example": "Knee replacement surgery"
},
"min": {
"type": "number",
"description": "The minimum cost for this component in this place of service, in dollars.",
"example": 239
},
"median": {
"type": "number",
"description": "The median cost for this component in this place of service, in dollars.",
"example": 520.535
},
"max": {
"type": "number",
"description": "The maximum cost for this component in this place of service, in dollars.",
"example": 714.93
}
}
}
}
},
"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."
}
],
"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."
}
},
"description": "The costs associated with this location."
},
"uuid": {
"type": "string",
"description": "A UUID uniquely identifying this location",
"format": "uuid",
"example": "f38b9fd5-1e28-4f6e-953c-1e1493b68e21"
},
"name": {
"type": "string",
"nullable": true
},
"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",
"nullable": true,
"example": "# 130"
},
"city": {
"type": "string",
"example": "San Francisco"
},
"state": {
"type": "string",
"example": "CA"
},
"zip": {
"type": "string",
"example": "94107"
}
}
},
"latitude": {
"type": "number",
"example": 37.7765973
},
"longitude": {
"type": "number",
"example": -122.3919488
},
"google_maps_link": {
"type": "string",
"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",
"description": "",
"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.",
"items": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"example": "2121234567"
},
"details": {
"type": "string",
"example": "secondary"
},
"confidence": {
"type": "integer",
"format": "int32",
"example": 3
}
}
}
},
"confidence": {
"type": "integer",
"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`.",
"format": "int32",
"nullable": true,
"example": 2
},
"insurances": {
"type": "array",
"description": "List of insurances the accepted at this location",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A UUID uniquely identifying this insurance",
"format": "uuid",
"example": "d8addf29-1054-4ccb-b179-dda65f7fefdd"
},
"carrier_association": {
"type": "string",
"nullable": true,
"example": "Aetna"
},
"carrier_brand": {
"type": "string",
"nullable": true,
"example": "Aetna"
},
"carrier_name": {
"type": "string",
"nullable": true,
"example": "Aetna"
},
"state": {
"type": "string",
"nullable": true,
"example": "NY"
},
"plan_name": {
"type": "string",
"nullable": true,
"example": "Aetna HealthFund Open Choice"
},
"plan_type": {
"type": "string",
"nullable": true,
"example": "PPO"
},
"metal_level": {
"type": "string",
"nullable": true
},
"display_name": {
"type": "string",
"example": "Aetna - HealthFund Open Choice - PPO"
},
"network": {
"type": "string",
"nullable": true
},
"confidence": {
"type": "integer",
"format": "int32",
"nullable": true,
"example": 4
},
"category": {
"type": "string",
"nullable": true
},
"codes": {
"type": "array",
"description": "",
"items": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
}
}
}
},
"tins": {
"type": "string",
"description": "Comma separated list of standard 9-digit identification code(s) used by the IRS for business entities and used for contracting and paying provider/facility claims."
}
},
"description": "All of the metadata on the matched location plus a `costs` key."
},
"npi": {
"maximum": 9999999999,
"minimum": 1000000000,
"type": "integer",
"description": "The healthcare provider's 10-digit National Provider Identifier (NPI)",
"format": "int32",
"example": 1861664294
},
"first_name": {
"type": "string",
"description": "First name of the provider",
"example": "Jane"
},
"middle_name": {
"type": "string",
"description": "Middle name of the provider",
"nullable": true,
"example": "J"
},
"last_name": {
"type": "string",
"description": "Last name of the provider",
"example": "Doe"
},
"age": {
"type": "integer",
"description": "The estimated age of the provider",
"format": "int32",
"nullable": true,
"example": 38
},
"gender": {
"type": "string",
"description": "The gender of the provider",
"enum": [
"m",
"f"
],
"x-enum-elements": [
{
"name": "m",
"description": ""
},
{
"name": "f",
"description": ""
}
]
},
"ratings_count": {
"type": "integer",
"description": "Total number of ratings collected across different sources",
"format": "int32",
"example": 20
},
"ratings_avg": {
"type": "number",
"description": "Average patient satisfaction rating out of 10 points across multiple sources",
"nullable": true,
"example": 9.8
},
"degrees": {
"type": "array",
"description": "Lists all degrees associated with this provider (e.g. MD, OD, PhD)",
"items": {
"type": "string"
}
},
"specialties": {
"type": "array",
"description": "This lists the UUIDs of all the specialties for a given provider",
"items": {
"type": "string",
"format": "uuid"
}
},
"languages": {
"type": "array",
"description": "List of confirmed languages spoken",
"items": {
"type": "string"
}
},
"educations": {
"type": "array",
"description": "List of the schools attended by the provider",
"items": {
"required": [
"education",
"type",
"year"
],
"type": "object",
"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",
"nullable": true
},
"year": {
"type": "integer",
"format": "int32",
"nullable": true,
"example": 2007
}
}
}
},
"insurances": {
"type": "array",
"description": "List of the UUIDs of insurances the provider accepts",
"items": {
"type": "string",
"format": "uuid"
}
},
"provider_types": {
"type": "array",
"description": "There are high level classifications for different provider types -- e.g. \"Doctor\", \"Optometry\", \"Dental Providers\", \"Nursing\", etc.",
"items": {
"type": "string"
}
},
"locations": {
"type": "array",
"description": "List of all locations this provider is known to practice at including any known phone numbers at these locations",
"items": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A UUID uniquely identifying this location",
"format": "uuid",
"example": "f38b9fd5-1e28-4f6e-953c-1e1493b68e21"
},
"name": {
"type": "string",
"nullable": true
},
"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",
"nullable": true,
"example": "# 130"
},
"city": {
"type": "string",
"example": "San Francisco"
},
"state": {
"type": "string",
"example": "CA"
},
"zip": {
"type": "string",
"example": "94107"
}
}
},
"latitude": {
"type": "number",
"example": 37.7765973
},
"longitude": {
"type": "number",
"example": -122.3919488
},
"google_maps_link": {
"type": "string",
"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",
"description": "",
"items": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"example": "4155146410"
},
"details": {
"type": "string",
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ribbon-health/refs/heads/main/json-schema/getpricingproviders.json