Ribbon Health Reference Endpoints API

openapi: 3.0.0
info:
  title: ribbon-health Cost Estimates Reference Endpoints 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: Reference Endpoints
  description: ''
paths:
  /custom/insurances:
    get:
      tags:
      - Reference Endpoints
      summary: getInsurances
      description: Search and list insurances that exist within the Ribbon API.
      operationId: getInsurances
      parameters:
      - name: search
        in: query
        required: false
        description: String input that fuzzy searches across `display_name`, `carrier_name`, and `uuid`.
        schema:
          type: string
        example: Aetna
      - name: carrier_association
        in: query
        required: false
        description: 'Comma separated list of the carrier association of insurances you are searching for.


          Note: This input must be an exact string match to work'
        schema:
          type: string
        example: BCBS Association
      - name: carrier_brand
        in: query
        required: false
        description: 'Comma separated list of the carrier brand of insurances you are searching for.


          Note: This input must be an exact string match to work'
        schema:
          type: string
        example: BCBS
      - name: carrier_name
        in: query
        required: false
        description: 'Comma separated list of the carrier name of insurances you are searching for.


          Note: This input must be an exact string match to work'
        schema:
          type: string
        example: Blue Cross Blue Shield of Illinois
      - name: state
        in: query
        required: false
        description: Two letter abbreviated state code of insurances you are searching for.
        schema:
          type: string
        example: NY
      - name: plan_name
        in: query
        required: false
        description: Exact string input of the plan name of insurances you are searching for.
        schema:
          type: string
        example: BlueCare Direct
      - name: plan_type
        in: query
        required: false
        description: Exact string input of the plan type of insurances you are searching for.
        schema:
          type: string
        example: PPO
      - name: display_name
        in: query
        required: false
        description: Exact string input of the display name of insurances you are searching for.
        schema:
          type: string
        example: Blue Cross Blue Shield of Illinois - BlueCare Direct - HMO
      - name: category
        in: query
        required: false
        description: 'Comma separated list of the category of insurances you are searching for.


          Note: This input must be an exact string match to work'
        schema:
          type: string
        example: Medicare Advantage
      - name: _excl_category
        in: query
        required: false
        description: 'Comma separated list of the category of insurances you wish to exclude.


          Note: This input must be an exact string match to work'
        schema:
          type: string
        example: Medicare Advantage
      - name: codes
        in: query
        required: false
        description: Single code input to search for plans with an exact string match within the codes field.
        schema:
          type: string
        example: H9572-001
      - name: partial_codes
        in: query
        required: false
        description: 'Partial string input to match to the codes field.

          For Medicare Advantage plans this is a contract ID (i.e. H9572). For Federal or State Exchange plans this is the first 10 digits of the HIOS ID (i.e. 36096il100)


          Note: This parameter can only be used if the `category` param is also utilized with a single category value.'
        schema:
          type: string
        example: H9572
      responses:
        '200':
          description: Insurances returned from a valid request
          content:
            application/json:
              schema:
                required:
                - count
                - next
                - previous
                - results
                type: object
                properties:
                  count:
                    type: integer
                    description: The total number of results matched, across all pages.
                    format: int32
                    example: 141
                  next:
                    type: string
                    nullable: true
                    example: https://api.ribbonhealth.com/v1/custom/insurances?search=aetna&page=3
                  previous:
                    type: string
                    nullable: true
                    example: https://api.ribbonhealth.com/v1/custom/insurances?search=aetna&page=1
                  results:
                    type: array
                    description: ''
                    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
        '400':
          description: A failure due to a malformed request
          content:
            application/json:
              schema:
                required:
                - error
                type: object
                properties:
                  error:
                    required:
                    - code
                    - message
                    - status
                    type: object
                    properties:
                      status:
                        type: integer
                        description: The HTTP error code associated with this error
                        format: int32
                        example: 400
                      code:
                        type: string
                        enum:
                        - invalid_query_params
                        - bad_request
                        x-enum-elements:
                        - name: invalid_query_params
                          description: ''
                        - name: bad_request
                          description: ''
                      message:
                        description: An object representing what exactly went wrong. The keys available in this object vary with the type of error  returned.
                        example:
                          query:
                            _schema:
                            - parameters 'npis' and 'location_ids' cannot be used together
                        oneOf:
                        - type: object
                        - type: string
                description: An error returned from the API
      deprecated: false
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
        ErrorTemplates: {}
        SkipAdditionalHeaders: false
      x-unitTests:
      - request:
          method: GET
          uri: /custom/insurances
        expectedResponse:
          x-allowExtraHeaders: true
          x-bodyMatchMode: NONE
          x-arrayOrderedMatching: false
          x-arrayCheckCount: false
          x-matchResponseSchema: true
          statusCode: '200'
          headers:
            Content-Type: application/json
        x-testShouldPass: true
        x-testEnabled: true
        x-testName: Test getInsurances
        x-testDescription: 'Search and list insurances that exist within the Ribbon API.

          '
    post:
      tags:
      - Reference Endpoints
      summary: postCustomInsurance
      description: 'Create a insurance with desired field values.

        '
      operationId: postCustomInsurance
      parameters: []
      requestBody:
        description: A JSON object mapping the name of the field to update to its new value
        content:
          application/json:
            schema:
              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
              description: A JSON object mapping the name of the field to update to its new value
        required: true
      responses:
        '201':
          description: Insurance was successfully created.
          content:
            application/json:
              schema:
                required:
                - data
                type: object
                properties:
                  data:
                    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
        '400':
          description: This request attempted to update with invalid schema or was missing required fields.
          content:
            application/json:
              schema:
                required:
                - error
                type: object
                properties:
                  error:
                    required:
                    - code
                    - message
                    - status
                    type: object
                    properties:
                      status:
                        type: integer
                        description: The HTTP error code associated with this error
                        format: int32
                        example: 400
                      code:
                        type: string
                        enum:
                        - invalid_query_params
                        - bad_request
                        x-enum-elements:
                        - name: invalid_query_params
                          description: ''
                        - name: bad_request
                          description: ''
                      message:
                        description: An object representing what exactly went wrong. The keys available in this object vary with the type of error  returned.
                        example:
                          query:
                            _schema:
                            - parameters 'npis' and 'location_ids' cannot be used together
                        oneOf:
                        - type: object
                        - type: string
                description: An error returned from the API
        '409':
          description: Insurance object with given fields already exists.
          content:
            application/json:
              schema:
                required:
                - error
                type: object
                properties:
                  error:
                    required:
                    - code
                    - message
                    - status
                    type: object
                    properties:
                      status:
                        type: integer
                        format: int32
                        example: 404
                      code:
                        type: string
                        enum:
                        - not_found
                      message:
                        type: string
                        enum:
                        - resource not found
                description: Resource with given fields aready exists
      deprecated: false
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
        ErrorTemplates: {}
        SkipAdditionalHeaders: false
      x-unitTests: []
  /custom/insurances/{insurance_uuid}:
    get:
      tags:
      - Reference Endpoints
      summary: getCustomInsurance
      description: 'Retrieve data on a specific insurance.

        '
      operationId: getCustomInsurance
      parameters:
      - name: insurance_uuid
        in: path
        description: The UUID of the target insurance.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
          example: 12403618-49d5-43ee-99ad-5e99194fe05c
      responses:
        '200':
          description: Returns a single insurance
          content:
            application/json:
              schema:
                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
        '404':
          description: The given insurance UUID cannot be found
          content:
            application/json:
              schema:
                required:
                - error
                type: object
                properties:
                  error:
                    required:
                    - code
                    - message
                    - status
                    type: object
                    properties:
                      status:
                        type: integer
                        format: int32
                        example: 404
                      code:
                        type: string
                        enum:
                        - not_found
                      message:
                        type: string
                        enum:
                        - resource not found
                description: The requested resource could not be found
      deprecated: false
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
        ErrorTemplates: {}
        SkipAdditionalHeaders: false
      x-unitTests:
      - request:
          method: GET
          uri: /custom/insurances/12403618-49d5-43ee-99ad-5e99194fe05c
        expectedResponse:
          x-allowExtraHeaders: true
          x-bodyMatchMode: NONE
          x-arrayOrderedMatching: false
          x-arrayCheckCount: false
          x-matchResponseSchema: true
          statusCode: '200'
          headers:
            Content-Type: application/json
        x-testShouldPass: true
        x-testEnabled: true
        x-testName: Test getCustomInsurance
        x-testDescription: 'Retrieve data on a specific insurance.

          '
    put:
      tags:
      - Reference Endpoints
      summary: putCustomInsurance
      description: 'Edit fields of a custom created insurance or a Ribbon created insurance.

        '
      operationId: putCustomInsurance
      parameters:
      - name: insurance_uuid
        in: path
        description: The UUID of the target insurance.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          format: uuid
          example: 12403618-49d5-43ee-99ad-5e99194fe05c
      requestBody:
        description: A JSON object mapping the name of the field to update to its new value
        content:
          application/json:
            schema:
              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
              description: A JSON object mapping the name of the field to update to its new value
        required: true
      responses:
        '200':
          description: The insurance object was successfully updated.
          content:
            application/json:
              schema:
                required:
                - data
                type: object
                properties:
                  data:
                    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
        '400':
          description: This request attempted to update with invalid schema or was missing required fields.
          content:
            application/json:
              schema:
                required:
                - error
                type: object
                properties:
                  error:
                    required:
                    - code
                    - message
                    - status
                    type: object
                    properties:
                      status:
                        type: integer
                        description: The HTTP error code associated with this error
                        format: int32
                        example: 400
                      code:
                        type: string
                        enum:
                        - invalid_query_params
                        - bad_request
                        x-enum-elements:
                        - name: invalid_query_params
                          description: ''
                        - name: bad_request
                          description: ''
                      message:
                        description: An object representing what exactly went wrong. The keys available in this object vary with the type of error  returned.
                        example:
                          query:
                            _schema:
                            - parameters 'npis' and 'location_ids' cannot be used together
                        oneOf:
                        - type: object
                        - type: string
                description: An error returned from the API
        '404':
          description: The given insurance UUID cannot be found
          content:
            application/json:
              schema:
                required:
                - error
                type: object
                properties:
                  error:
                    required:
                    - code
                    - message
                    - status
                    type: object
             

# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ribbon-health/refs/heads/main/openapi/ribbon-health-reference-endpoints-api-openapi.yml