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