openapi: 3.2.0
info:
  title: Ribbon Health Focus Area Endpoints 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: Focus Area Endpoints
paths:
  /custom/clinical_areas:
    get:
      summary: Search Clinical Areas
      description: 'Returns clinical areas that exist within the Ribbon API.

        '
      operationId: getClinicalAreas
      tags:
      - Focus Area Endpoints
      parameters:
      - name: Clinical Area Search Parameters
        in: query
        required: false
        description: Search parameters for the clinical area endpoint.
        explode: true
        schema:
          type: object
          properties:
            page:
              type: integer
              example: 1
              description: The page of the results which was returned.
            page_size:
              type: integer
              example: 25
              description: How many results are in each page.
            search:
              type: string
              example: X-ray
              description: 'String input that fuzzy searches against key fields within each clinical area object to return the most relevant options.

                '
            clinical_area:
              type: string
              example: Nutrition
              description: String input that fuzzy searches on `display` field.
            _excl_clinical_area_ids:
              type: string
              example: ffce41b2-aba4-4202-beba-6aa9dc51ef37,fe7d808b-5f53-4024-af9d-2662515bcd83
              description: Comma separated list of clinical area UUIDs to exclude from search results.
            specialty_ids:
              type: string
              example: fcc9a22c-7a0f-4405-b0c9-c5f8ad83b93e,8b5d3998-d7e2-4b9e-91d1-17c19cd089f5
              description: Comma separated list of specialty UUIDs.
            condition:
              type: string
              example: Sleep Disorders
              description: String input that fuzzy searches on `condition.display` field.
            condition_ids:
              type: string
              example: 45c9a22c-7a0f-4405-b0c9-c5f8ad83ba32,219d3998-d7e2-4b9e-91d1-17c19cd0bbc2
              description: Comma separated list of condition UUIDs.
            treatment:
              type: string
              example: ACL Surgery
              description: String input that fuzzy searches on `treatment.display` field.
            treatment_ids:
              type: string
              example: bb2ca22c-7a0f-4405-b0c9-c5f8ad839898,2ce33998-d7e2-4b9e-91d1-17c19cd06012
              description: Comma separated list of treatment UUIDs.
            type:
              type: string
              example: providers
              description: 'String input of the type of clinical areas to return. Options for input are either `providers` or `locations`.

                Note: Defaults to returning all clinical areas of any type.

                '
      responses:
        '200':
          description: Clinical areas returned from a valid request
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - next
                - previous
                - parameters
                - results
                properties:
                  count:
                    type: integer
                    description: The total number of results matched, across all pages.
                    example: 107
                  next:
                    type:
                    - string
                    - 'null'
                    example: https://api.ribbonhealth.com/v1/custom/clinical_areas?page=3
                  previous:
                    type:
                    - string
                    - 'null'
                    example: https://api.ribbonhealth.com/v1/custom/clinical_areas?page=1
                  parameters:
                  - $ref: '#/paths/~1custom~1clinical_areas/get/parameters/0'
                  results:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1clinical_areas~1%7Bclinical_area_uuid%7D/get/responses/200/content/application~1json/schema'
        '400':
          description: Each request can only perform one search
          content:
            application/json:
              schema:
                $ref: '#/paths/~1network_analysis/get/responses/400/content/application~1json/schema'
  /custom/clinical_areas/{clinical_area_uuid}:
    get:
      summary: Get Clinical Area
      description: 'Retrieve data on a specific clinical area.

        '
      operationId: getClinicalArea
      tags:
      - Focus Area Endpoints
      parameters:
      - name: clinical_area_uuid
        in: path
        required: true
        description: The UUID of the target clinical area.
        schema:
          type: string
          format: uuid
          example: f352b596-dfb0-494f-9a03-224794f5d182
      responses:
        '200':
          description: Returns a single clinical area
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    format: uuid
                    example: f352b596-dfb0-494f-9a03-224794f5d182
                    description: A UUID uniquely identifying this clinical area
                  display:
                    type: string
                    example: Substance Disorders (e.g. Opioid, Cocaine, Alcohol)
                  types:
                    type: array
                    items:
                      type: string
                      enum:
                      - providers
                      - locations
                  conditions:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1conditions~1%7Bcondition_uuid%7D/get/responses/200/content/application~1json/schema'
                  treatments:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1treatments~1%7Btreatment_uuid%7D/get/responses/200/content/application~1json/schema'
                  specialties:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1specialties~1%7Bspecialty_uuid%7D/get/responses/200/content/application~1json/schema'
        '404':
          description: The given clinical area UUID cannot be found
          content:
            application/json:
              schema:
                $ref: '#/paths/~1custom~1tin~1%7Btin_id%7D/get/responses/404/content/application~1json/schema'
  /custom/conditions:
    get:
      summary: Search Conditions
      description: 'Returns conditions that exist within the Ribbon API.

        '
      operationId: getConditions
      tags:
      - Focus Area Endpoints
      parameters:
      - name: Condition Search Parameters
        in: query
        required: false
        description: Search parameters for the condition endpoint.
        explode: true
        schema:
          type: object
          properties:
            page:
              type: integer
              example: 1
              description: The page of the results which was returned.
            page_size:
              type: integer
              example: 25
              description: How many results are in each page.
            search:
              type: string
              description: 'String input that fuzzy searches against key fields within each condition object to return the most relevant options.

                '
              example: depression
            _excl_condition_ids:
              type: string
              example: 2938baf9-f064-44d6-8251-6e4b9fbb6fd2,c9d21735-8a78-45fe-982b-d216cb94beb7
              description: Comma separated list of condition UUIDs to exclude from search results.
            specialty_ids:
              type: string
              example: fcc9a22c-7a0f-4405-b0c9-c5f8ad83b93e,8b5d3998-d7e2-4b9e-91d1-17c19cd089f5
              description: Comma separated list of specialty UUIDs.
            module:
              type: string
              example: focus_areas
              description: 'String input of the type of clinical areas to return. Options for input are either `focus_areas` or `condition_cost_estimate`.

                Note: This input must be an exact string match to work

                '
      responses:
        '200':
          description: Conditions returned from a valid request
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - next
                - previous
                - parameters
                - results
                properties:
                  count:
                    type: integer
                    description: The total number of results matched, across all pages.
                    example: 480
                  next:
                    type:
                    - string
                    - 'null'
                    example: https://api.ribbonhealth.com/v1/custom/conditions?page=3
                  previous:
                    type:
                    - string
                    - 'null'
                    example: https://api.ribbonhealth.com/v1/custom/conditions?page=1
                  parameters:
                  - $ref: '#/paths/~1custom~1conditions/get/parameters/0'
                  results:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1conditions~1%7Bcondition_uuid%7D/get/responses/200/content/application~1json/schema'
        '400':
          description: Module does not exist
          content:
            application/json:
              schema:
                $ref: '#/paths/~1network_analysis/get/responses/400/content/application~1json/schema'
  /custom/conditions/{condition_uuid}:
    get:
      summary: Get Condition
      description: 'Retrieve data on a specific condition.

        '
      operationId: getCondition
      tags:
      - Focus Area Endpoints
      parameters:
      - name: condition_uuid
        in: path
        required: true
        description: The UUID of the target condition.
        schema:
          type: string
          format: uuid
          example: fd7c10f3-fbec-482a-929b-be94a8bb3bc1
      responses:
        '200':
          description: Returns a single condition
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    format: uuid
                    example: 99f4762e-c4c2-4d1d-983a-2b8b303e691d
                    description: A UUID uniquely identifying this condition
                  display:
                    type: string
                    example: Chronic Depression
                  types:
                    type: array
                    items:
                      type: string
                      enum:
                      - focus_areas
                      - condition_cost_estimate
                  specialties:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1specialties~1%7Bspecialty_uuid%7D/get/responses/200/content/application~1json/schema'
                  modules:
                    type: array
                    items:
                      type: string
        '404':
          description: The given condition UUID cannot be found
          content:
            application/json:
              schema:
                $ref: '#/paths/~1custom~1tin~1%7Btin_id%7D/get/responses/404/content/application~1json/schema'
  /custom/treatments:
    get:
      summary: Search Treatments
      description: 'Returns treatments that exist within the Ribbon API.

        '
      operationId: getTreatments
      tags:
      - Focus Area Endpoints
      parameters:
      - name: Treatment Search Parameters
        in: query
        required: false
        description: Search parameters for the treatment endpoint.
        explode: true
        schema:
          type: object
          properties:
            page:
              type: integer
              example: 1
              description: The page of the results which was returned.
            page_size:
              type: integer
              example: 25
              description: How many results are in each page.
            search:
              type: string
              description: 'String input that fuzzy searches against key fields within each treatment object to return the most relevant options.

                '
              example: Ankle X-Ray
            _excl_treatment_ids:
              type: string
              example: ffb31993-8265-45f6-98ac-18a495d614b5,ff36f4f1-7031-46b0-a297-e85b73aa8e90
              description: Comma separated list of treatment UUIDs to exclude from search results.
            specialty_ids:
              type: string
              example: fcc9a22c-7a0f-4405-b0c9-c5f8ad83b93e,8b5d3998-d7e2-4b9e-91d1-17c19cd089f5
              description: Comma separated list of specialty UUIDs.
            type:
              type: string
              example: providers
              description: 'String input of the type of clinical areas to return. Options for input are either `providers` or `locations`.

                Note: Defaults to returning all clinical areas of any type.

                '
      responses:
        '200':
          description: Treatments returned from a valid request
          content:
            application/json:
              schema:
                type: object
                required:
                - count
                - next
                - previous
                - parameters
                - results
                properties:
                  count:
                    type: integer
                    description: The total number of results matched, across all pages.
                    example: 477
                  next:
                    type:
                    - string
                    - 'null'
                    example: https://api.ribbonhealth.com/v1/custom/treatments?page=3
                  previous:
                    type:
                    - string
                    - 'null'
                    example: https://api.ribbonhealth.com/v1/custom/treatments?page=1
                  parameters:
                  - $ref: '#/paths/~1custom~1treatments/get/parameters/0'
                  results:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1treatments~1%7Btreatment_uuid%7D/get/responses/200/content/application~1json/schema'
  /custom/treatments/{treatment_uuid}:
    get:
      summary: Get Treatment
      description: 'Retrieve data on a specific treatment.

        '
      operationId: getTreatment
      tags:
      - Focus Area Endpoints
      parameters:
      - name: treatment_uuid
        in: path
        required: true
        description: The UUID of the target treatment.
        schema:
          type: string
          format: uuid
          example: 88a70b34-d0a7-47e2-89ac-4fed203eca2f
      responses:
        '200':
          description: Returns a single treatment
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid:
                    type: string
                    format: uuid
                    example: 88a70b34-d0a7-47e2-89ac-4fed203eca2f
                    description: A UUID uniquely identifying this treatment
                  display:
                    type: string
                    example: Knee Replacement
                  types:
                    type: array
                    items:
                      type: string
                      enum:
                      - providers
                      - locations
                  specialties:
                    type: array
                    items:
                      $ref: '#/paths/~1custom~1specialties~1%7Bspecialty_uuid%7D/get/responses/200/content/application~1json/schema'
        '404':
          description: The given treatment UUID cannot be found
          content:
            application/json:
              schema:
                $ref: '#/paths/~1custom~1tin~1%7Btin_id%7D/get/responses/404/content/application~1json/schema'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer