H1 Cost Estimates API
The Cost Estimates API from H1 — 4 operation(s) for cost estimates.
OpenAPI Specification
openapi: 3.2.0
info:
title: Ribbon Health Cost Estimates API
version: 1.0.0
description: 'An API for interacting with the data provided by Ribbon Health, including information about healthcare providers, locations, insurances, and more.
'
servers:
- url: https://api.ribbonhealth.com/v1
security:
- BearerAuth: []
tags:
- name: Cost Estimates
paths:
/eligibility:
post:
summary: Check Member Eligibility
description: 'Verify a member''s current insurance coverage and benefits. You can access detailed information including a member’s progress on their Deductible and Out-of-pocket, as well as Copay and Coinsurance information for different services.
#### Example Use Case
Inform a member of their current progress against their Deductible as well as their Copay and Coinsurance summaries so they can better estimate their out-of pocket costs.
'
operationId: getEligibility
tags:
- Cost Estimates
parameters:
- name: include_full_response
in: query
required: false
description: Whether to return the full eligibility response from the payer. Defaults to `false` when not provided.
schema:
type: boolean
default: false
example: true
requestBody:
required: true
description: Identifying information for the member to be checked
content:
application/json:
schema:
type: object
properties:
member_id:
type: string
example: 000000000-00
description: The member's identification number
first_name:
type: string
example: John
description: The member's first name
last_name:
type: string
example: Doe
description: The member's last name
birth_date:
type: string
format: date
example: '1980-12-31'
description: The member's birth date as an ISO-format date string
insurance_partner:
type: string
example: aetna_better_health_il
description: The identifier for this insurance partner in the Ribbon API
responses:
'200':
description: Eligibility information for the given member
content:
application/json:
schema:
type: object
required:
- parameters
- status
- request_id
properties:
parameters:
type: object
properties:
member_id:
type: string
example: 000000000-00
description: The member's identification number
first_name:
type: string
example: John
description: The member's first name
last_name:
type: string
example: Doe
description: The member's last name
birth_date:
type: string
format: date
example: '1980-12-31'
description: The member's birth date as an ISO-format date string
insurance_partner:
type: string
example: aetna_better_health_il
description: The identifier for this insurance partner in the Ribbon API
status:
type: object
properties:
is_valid:
type: boolean
example: true
description: Whether the eligibility check was successful
error:
type:
- string
- 'null'
description: If `is_valid` is `true`, an error code explaining what went wrong. When `is_valid` is `false`, this will be `null`.
request_id:
type: string
example: '40610978'
description: A unique identifier for the given response which Ribbon can use to find it in our logs during support requests
plan_info:
type: object
properties:
insurance_partner:
type: string
example: aetna_better_health_il
description: The identifier for this insurance partner in the Ribbon API
plan_name:
type: string
example: Aetna Better Health of Illinois
description: User-friendly display name for this insurance partner
is_active:
type: boolean
example: true
description: Whether the member is actively covered by this plan
plan_start_date:
type: string
format: date
example: '2012-02-01'
description: The starting date for the member's coverage by this plan
plan_end_date:
type:
- string
- 'null'
format: date
example: '2024-01-01'
description: The ending date for the member's coverage by this plan
deductible_detail:
type: object
properties:
individual:
type: object
properties:
in_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards in-network deductibles, in dollars
maximum:
type:
- string
- 'null'
example: '3000'
description: The maximum amount the member can pay towards in-network deductibles, in dollars
remaining:
type: string
example: '2983.57'
description: The remaining amount the member can pay towards in-network deductibles, in dollars
out_of_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards out-of-network deductibles, in dollars
maximum:
type:
- string
- 'null'
example: '6000'
description: The maximum amount the member can pay towards out-of-network deductibles, in dollars
remaining:
type:
- string
- 'null'
example: '5983.57'
description: The remaining amount the member can pay towards out-of-network deductibles, in dollars
family:
type: object
properties:
in_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards in-network deductibles, in dollars
maximum:
type:
- string
- 'null'
example: '6000'
description: The maximum amount the member can pay towards in-network deductibles, in dollars
remaining:
type:
- string
- 'null'
example: '5983.57'
description: The remaining amount the member can pay towards in-network deductibles, in dollars
out_of_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards out-of-network deductibles, in dollars
maximum:
type:
- string
- 'null'
example: '12000'
description: The maximum amount the member can pay towards out-of-network deductibles, in dollars
remaining:
type:
- string
- 'null'
example: '11983.57'
description: The remaining amount the member can pay towards out-of-network deductibles, in dollars
out_of_pocket_detail:
type: object
properties:
individual:
type: object
properties:
in_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards their in-network out-of-pocket maximum, in dollars
maximum:
type:
- string
- 'null'
example: '3000'
description: The maximum amount the member can pay towards their in-network out-of-pocket maximum, in dollars
remaining:
type:
- string
- 'null'
example: '2983.57'
description: The remaining amount the member can pay towards their in-network out-of-pocket maximum, in dollars
out_of_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards their out-of-network out-of-pocket maximum, in dollars
maximum:
type:
- string
- 'null'
example: '6000'
description: The maximum amount the member can pay towards their out-of-network out-of-pocket maximum, in dollars
remaining:
type:
- string
- 'null'
example: '5983.57'
description: The remaining amount the member can pay towards their out-of-network out-of-pocket maximum, in dollars
family:
type: object
properties:
in_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards their in-network out-of-pocket maximum, in dollars
maximum:
type:
- string
- 'null'
example: '6000'
description: The maximum amount the member can pay towards their in-network out-of-pocket maximum, in dollars
remaining:
type:
- string
- 'null'
example: '5983.57'
description: The remaining amount the member can pay towards their in-network out-of-pocket maximum, in dollars
out_of_network:
type: object
properties:
spend:
type:
- string
- 'null'
example: '16.43'
description: The amount the member has paid towards their out-of-network out-of-pocket maximum, in dollars
maximum:
type:
- string
- 'null'
example: '12000'
description: The maximum amount the member can pay towards their out-of-network out-of-pocket maximum, in dollars
remaining:
type:
- string
- 'null'
example: '11983.57'
description: The remaining amount the member can pay towards their out-of-network out-of-pocket maximum, in dollars
primary_care_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
dme_summary:
type: object
properties:
in_network:
type: object
properties:
copay:
type: string
example: '30.0'
description: The amount of the member's in-network copay, in dollars
coinsurance:
type:
- string
- 'null'
example: '0.0'
out_of_network:
type: object
properties:
copay:
type: string
example: '30.0'
description: The amount of the member's out-of-network copay, in dollars
coinsurance:
type:
- string
- 'null'
example: '0.0'
oncology_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
vision_optometry_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
physical_therapy_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
specialist_office_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
mental_health_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
surgical_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
urgent_care_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
diagnostic_lab_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
asc_facility_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
chiropractic_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
mri_ct_scan_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
x_ray_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
speech_therapy_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
occupational_therapy_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
emergency_medical_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
wellness_or_routine_visit_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
podiatry_office_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
outpatient_professional_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
anesthesia_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
substance_abuse_professional_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
substance_abuse_in_patient_facility_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
substance_abuse_out_patient_facility_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
flu_vaccination_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
hospital_inpatient_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
pharmacy_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
hospital_outpatient_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
telemedicine_primary_care_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
telemedicine_specialist_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
telemedicine_urgent_care_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
telemedicine_physical_therapy_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
telemedicine_mental_health_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
psychotherapy_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
snf_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
snf_room_board_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
home_health_care_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
hospice_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
professional_physician_visit_inpatient_summary:
$ref: '#/paths/~1eligibility/post/responses/200/content/application~1json/schema/properties/dme_summary'
x-readme:
explorer-enabled: false
/eligibility_insurance_partners:
get:
summary: Search Supported Eligibility Insurances
description: 'Search or list all insurance partners supported by our eligibility features.
'
operationId: getEligibilityInsurancePartners
tags:
- Cost Estimates
parameters:
- name: search
in: query
required: false
description: Fuzzy search input for insurance names
schema:
type: string
example: aetna
responses:
'200':
description: Returns a list of supported insurances
content:
application/json:
schema:
type: object
required:
- count
- data
properties:
count:
type: integer
example: 332
description: The total number of results matched.
data:
type: array
items:
$ref: '#/paths/~1eligibility_insurance_partners~1%7Binsurance_partner%7D/get/responses/200/content/application~1json/schema'
/eligibility_insurance_partners/{insurance_partner}:
get:
summary: Get Eligibility Insurance
description: 'Fetch an insurance partner supported by our eligibility features.
'
operationId: getEligibilityInsurancePartner
tags:
- Cost Estimates
parameters:
- name: insurance_partner
in: path
required: true
description: The identifier for this insurance partner in the Ribbon API
schema:
type: string
example: aetna_better_health_il
responses:
'200':
description: Returns a single supported insurance
content:
application/json:
schema:
type: object
properties:
insurance_partner:
type: string
example: aetna_better_health_il
description: Identifier for this insurance partner used by other endpoints in the Ribbon API
display:
type: string
example: Aetna Better Health of Illinois
description: User-friendly display name for this insurance partner
'404':
description: The given insurance partner identifier cannot be found
content:
application/json:
schema:
$ref: '#/paths/~1custom~1tin~1%7Btin_id%7D/get/responses/404/content/application~1json/schema'
/procedure_cost_estimate:
get:
summary: Procedure Cost Estimate
description: 'Calculates estimated costs for a given procedure based on a user''s location.
#### Example Use Case
Estimate the cost of a knee replacement surgery for a user in Boston so they can plan their personal finances accordingly.
'
operationId: getProcedureCostEstimate
tags:
- Cost Estimates
parameters:
- name: procedure_ids
in: query
required: true
description: The UUIDs of the procedures to filter results to, as a comma-delimited string
schema:
type: string
example: 9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae,fbb223e6-9806-45b5-95b1-4d7a36cc9164
- name: member_zip
in: query
required: true
description: The zip code of the member we are generating cost estimates for
schema:
type: string
example: '60606'
- name: type
in: query
required: false
description: 'The type of data to base cost estimates on: `claims` data or payer-filed `price_transparency` data. Defaults to `claims`.'
schema:
type: string
enum:
- claims
- price_transparency
default: claims
example: price_transparency
- name: plan_id
in: query
required: false
description: The UUID of the insurance plan to use when fetching negotiated rates with providers. Necessary only if searching for estimates using the 'price_transparency' `type`.
schema:
type: string
format: uuid
example: a5a0c8ff-c62b-4a9e-af86-55e52bd7dc55
responses:
'200':
description: Estimated costs for the given procedures
content:
application/json:
schema:
type: object
properties:
parameters:
type: object
properties:
procedures:
type: array
items:
$ref: '#/paths/~1procedures~1%7Bprocedure_uuid%7D/get/responses/200/content/application~1json/schema'
member_zip:
type: string
example: '60606'
data:
type: object
properties:
cost_estimates:
type: object
properties:
minimum:
type: number
example: 100
description: Minimum cost for all of the given procedures combined.
median:
type: number
example: 300
description: Median cost for all of the given procedures combined.
maximum:
type: number
example: 500
description: Maximum cost for all of the given procedures combined.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer