openapi: 3.0.0
info:
title: ribbon-health Cost Estimates Price Transparency API
description: 'An API for interacting with the data provided by Ribbon Health, including information about healthcare providers, locations, insurances, and more.
'
contact: {}
version: 1.0.0
x-codegen-settings:
Nullify404: false
GenerateAsyncCode: true
UseMethodPrefix: false
UseModelPostfix: false
UseControllerPrefix: true
UseEnumPostfix: true
CollectParameters: false
UseConstructorsForConfig: false
UseCommonSDKLibrary: false
iOSUseAppInfoPlist: false
AndroidUseAppManifest: false
BodySerialization: 0
EnableAdditionalModelProperties: false
PreserveParameterOrder: true
AppendContentHeaders: true
iOSGenerateCoreData: false
GenerateInterfaces: false
NodeHttpClient: NODE_REQUEST
ValidateRequiredParameters: false
JavaUsePropertiesConfig: false
Timeout: 0
StoreTimezoneInformation: false
EnablePHPComposerVersionString: false
EnableLogging: false
ArraySerialization: Indexed
ModelSerializationScheme: Json
UseExceptionPrefix: true
RunscopeEnabled: false
AndroidHttpClient: ANDROID_OK
ObjCHttpClient: UNIREST
CSharpHttpClient: UNIREST
PHPHttpClient: UNIREST
JavaHttpClient: JAVA_OK
ParameterArrayFormat: ParamArrayWithIndex
SecurityProtocols:
- Ssl3
- Tls
GenerateTravisConfig: false
GenerateCircleConfig: false
GenerateAppveyorConfig: false
GenerateJenkinsConfig: false
EnableHttpCache: false
Retries: 0
RetryInterval: 1
GenerateAdvancedDocs: true
UnderscoreNumbers: true
UseSingletonPattern: true
DisableLinting: false
ApplyCustomizations: []
SortResources: false
AllowSkippingSSLCertVerification: false
DoNotSplitWords: []
EnableGlobalUserAgent: true
ReturnCompleteHttpResponse: false
GenerateModels: true
GenerateExceptions: true
IgnoreIfNullJson: false
DisableDocs: false
LiftParameterDescriptionFromCustomType: false
ThrowForHttpErrorStatusCodes: true
ResponseMapping:
Type: Simple
ForceKeywordArgsInRuby: false
SymbolizeHashKeysInRuby: false
UsageExampleEndpoint:
Description: ''
EndpointGroupName: ''
EndpointName: ''
IsLatestVersion: false
EnableImmutableModels: false
GenerateEnums: true
BackoffFactor: 2
StatusCodesToRetry:
- 408
- 413
- 429
- 500
- 502
- 503
- 504
- 521
- 522
- 524
RequestMethodsToRetry:
- GET
- PUT
UserConfigurableRetries: true
UseEndpointMethodName: false
EncodeTemplateParameters: true
GenerateExamplesForOptionalFields: false
MultitargetDotnetVersions: false
BackoffMax: 0
RetryOnTimeout: true
EnableCookies: false
EnableJsonPassThroughForAny: false
PascalCaseEnumForCSharp: false
PascalCaseEnumForTypeScript: false
DisableMultipleAuth: false
AddSingleAuthDeprecatedCode: true
EnableExperimentalTypeCombinatorGeneration: false
ErrorTemplates: {}
UseSecuritySchemeNameForSingleAuth: false
EnableModelKeywordArgsInRuby: false
NullifyEmptyResponses: false
ExtendedAdditionalPropertiesSupport: false
EnforceStandardizedCasing: false
x-server-configuration:
default-environment: production
default-server: default
environments:
- name: production
servers:
- name: default
url: https://api.ribbonhealth.com/v1
parameters: []
x-image-uri: ''
servers:
- url: https://api.ribbonhealth.com/v1
security:
- BearerAuth: []
tags:
- name: Price Transparency
description: ''
paths:
/pricing/providers:
get:
tags:
- Price Transparency
summary: getPricingProviders
description: 'Search for providers that perform a given procedure and find the lowest insurance-specific price for a procedure in your area.
#### Example Use Case
Search for all applicable provider negotiated rates, given a specific insurance and procedure (and optionally, a specific location/address and distance). For example, search for all providers near me who perform Leg MRIs and who take a given insurance, sorted by lowest price.
'
operationId: getPricingProviders
parameters:
- name: procedure_id
in: query
required: false
description: 'Search for prices for the procedure with the given UUID.
If the given ID is for a procedure bundle but do not have data for the insurance specified by the `plan_id` parameter, we will return data for its anchor procedure instead.
Exactly one of `procedure`, `procedure_id`, or `procedure_code` must be specified.'
schema:
type: string
format: uuid
example: 7ad7c4ef-baf9-4789-8e58-51d2308a1143
- name: procedure
in: query
required: false
description: 'Search for prices for the given procedure. This input is fuzzy matched to the most relevant procedure `display` field.
We will preferentially match procedure bundles. If we match a procedure bundle but do not have data for the insurance specified by the `plan_id` parameter, we will return data for its anchor procedure instead.
Exactly one of `procedure`, `procedure_id`, or `procedure_code` must be specified.'
schema:
type: string
example: MRI, thoracic spine
- name: procedure_code
in: query
required: false
description: 'Search for prices for procedures with the given billing code.
We will preferentially match procedure bundles. If we match a procedure bundle but do not have data for the insurance specified by the `plan_id` parameter, we will return data for its anchor procedure instead.
Exactly one of `procedure`, `procedure_id`, or `procedure_code` must be specified.'
schema:
type: string
example: '73720'
- name: page
in: query
required: false
description: The page of the results which was returned.
schema:
type: integer
format: int32
example: 1
- name: page_size
in: query
required: false
description: How many results are in each page.
schema:
type: integer
format: int32
example: 25
- name: plan_id
in: query
required: false
description: Search for negotiated rates for the insurance plan with this UUID.
schema:
type: string
format: uuid
example: 81ba3a1a-05a9-48d9-b9b2-cb8f9eafc902
- name: specialty_ids
in: query
required: false
description: A comma separated list of specialty UUIDs. Filter to providers with any of the given specialties.
schema:
type: string
example: fcc9a22c-7a0f-4405-b0c9-c5f8ad83b93e,8b5d3998-d7e2-4b9e-91d1-17c19cd089f5,44b0284c-f360-4312-a17d-d601651cb0ea
- name: specialty
in: query
required: false
description: String input of a provider specialty that will be interpreted and matched to the single closest specialty, dealing with basic typos and colloquial names for providers.
schema:
type: string
example: gastroenterology
- name: address
in: query
required: false
description: String input of an address that will be interpreted and geocoded in real time.
schema:
type: string
example: 2074 23rd Ave, San Francisco, CA 94116
- name: location
in: query
required: false
description: Latitude/longitude pair of coordinates in lieu of a string address.
schema:
type: string
example: 37.7489816,-122.4802092
- name: distance
in: query
required: false
description: The proximity radius of providers returned.
schema:
type: integer
format: int32
example: 10
- name: fields
in: query
required: false
description: 'Comma-separated 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.
Note that all price information is nested under the `matched_location` field. You almost certainly want to return this field.
Cannot be used in tandem with `_excl_fields`.'
schema:
type: string
example: matched_location,npi
- name: _excl_fields
in: query
required: false
description: 'Comma-separated 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.
Cannot be used in tandem with `fields`.'
schema:
type: string
example: insurances,age
responses:
'200':
description: Returns per provider prices for the given procedure
content:
application/json:
schema:
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.
Only 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.
Note that all price information is nested under the `matched_location` field. You almost certainly want to return this field.
Cannot 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.
Cannot 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.
For 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.
This 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.
This 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.
For 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.
This 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.
This 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.
This 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
This field will only be populated for Ribbon-provided locations. Locations you c
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ribbon-health/refs/heads/main/openapi/ribbon-health-price-transparency-api-openapi.yml