Ribbon Health Providers API

openapi: 3.0.0
info:
  title: ribbon-health Cost Estimates Providers 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: Providers
  description: ''
paths:
  /custom/providers:
    get:
      tags:
      - Providers
      summary: getCustomProviders
      description: Allows you to quickly list doctors based on important search criteria.
      operationId: getCustomProviders
      parameters:
      - name: page
        in: query
        description: The page number to return.
        required: false
        schema:
          type: integer
        example: 1
      - name: page_size
        in: query
        description: Number of items per page.
        required: false
        schema:
          type: integer
        example: 25
      - name: max_locations
        in: query
        description: Max number of locations returned per provider.
        required: false
        schema:
          type: integer
        example: 5
      - name: fields
        in: query
        description: Comma-separated list of fields to include.
        required: false
        schema:
          type: string
        example: locations,age
      - name: _excl_fields
        in: query
        description: Comma-separated list of fields to exclude.
        required: false
        schema:
          type: string
        example: locations,age
      - name: npis
        in: query
        description: A comma-separated list of NPIs to filter on.
        required: false
        schema:
          type: string
        example: 1234567890
      - name: name
        in: query
        description: Provider’s name or partial name to search.
        required: false
        schema:
          type: string
        example: Doe
      - name: provider_types
        in: query
        description: Comma-separated list of provider types to include.
        required: false
        schema:
          type: string
        example: Optometry
      - name: _excl_provider_types
        in: query
        description: Comma-separated list of provider types to exclude.
        required: false
        schema:
          type: string
        example: Optometry
      - name: gender
        in: query
        description: Filter providers by gender (e.g., 'm', 'f').
        required: false
        schema:
          type: string
        example: m
      - name: max_age
        in: query
        description: Maximum provider age to include.
        required: false
        schema:
          type: integer
        example: 70
      - name: min_age
        in: query
        description: Minimum provider age to include.
        required: false
        schema:
          type: integer
        example: 45
      - name: language
        in: query
        description: Provider’s language (or comma-separated languages).
        required: false
        schema:
          type: string
        example: English
      - name: _excl_language
        in: query
        description: Language(s) to exclude.
        required: false
        schema:
          type: string
        example: English
      - name: min_rating
        in: query
        description: Minimum star rating allowed.
        required: false
        schema:
          type: integer
        example: 6
      - name: address
        in: query
        description: Free-text address to search.
        required: false
        schema:
          type: string
        example: New York, NY
      - name: location_ids
        in: query
        description: Comma-separated list of location IDs to include.
        required: false
        schema:
          type: string
        example: 34ecc98a-e49e-49e3-84f9-b0ab2ff00495
      - name: _excl_location_ids
        in: query
        description: Comma-separated list of location IDs to exclude.
        required: false
        schema:
          type: string
        example: 34ecc98a-e49e-49e3-84f9-b0ab2ff00495
      - name: location
        in: query
        description: A latitude,longitude pair for proximity searching.
        required: false
        schema:
          type: string
        example: 37.7489816,-122.4802092
      - name: min_location_confidence
        in: query
        description: Minimum location confidence score to include.
        required: false
        schema:
          type: integer
        example: 3
      - name: min_confidence
        in: query
        description: (Synonym to min_location_confidence, if used.)
        required: false
        schema:
          type: integer
        example: 3
      - name: distance
        in: query
        description: Distance in miles from the given location.
        required: false
        schema:
          type: integer
        example: 10
      - name: state
        in: query
        description: Two-letter US state code (e.g., "NY").
        required: false
        schema:
          type: string
        example: NY
      - name: insurance_ids
        in: query
        description: Comma-separated insurance IDs to include.
        required: false
        schema:
          type: string
        example: e527f6e3-fe42-4932-bf34-d81f1c1fd652
      - name: _excl_insurance_ids
        in: query
        description: Comma-separated insurance IDs to exclude.
        required: false
        schema:
          type: string
        example: e527f6e3-fe42-4932-bf34-d81f1c1fd652
      - name: insurance_carrier_name
        in: query
        description: Filter providers by insurance carrier name.
        required: false
        schema:
          type: string
        example: Aetna
      - name: location_insurance_ids
        in: query
        description: Comma-separated insurance IDs applicable at certain locations.
        required: false
        schema:
          type: string
        example: 34ecc98a-e49e-49e3-84f9-b0ab2ff00495
      - name: _excl_location_insurance_ids
        in: query
        description: Comma-separated insurance IDs to exclude at locations.
        required: false
        schema:
          type: string
        example: 34ecc98a-e49e-49e3-84f9-b0ab2ff00495
      - name: national_bluecard
        in: query
        description: True if searching for BlueCard or national Blue network coverage.
        required: false
        schema:
          type: boolean
        example: true
      - name: specialty_ids
        in: query
        description: Comma-separated list of specialty IDs to include.
        required: false
        schema:
          type: string
        example: 1de33770-eb1c-47fa-ab3e-f9a4ab924d9d
      - name: _excl_specialty_ids
        in: query
        description: Comma-separated list of specialty IDs to exclude.
        required: false
        schema:
          type: string
        example: 1de33770-eb1c-47fa-ab3e-f9a4ab924d9d
      - name: specialty
        in: query
        description: Specialty name to include.
        required: false
        schema:
          type: string
        example: gastroenterology
      - name: specialty_ids_primary
        in: query
        description: Comma-separated list of primary specialty IDs to include.
        required: false
        schema:
          type: string
        example: 1de33770-eb1c-47fa-ab3e-f9a4ab924d9d
      - name: _excl_specialty_ids_primary
        in: query
        description: Comma-separated list of primary specialty IDs to exclude.
        required: false
        schema:
          type: string
        example: 1de33770-eb1c-47fa-ab3e-f9a4ab924d9d
      - name: specialty_primary
        in: query
        description: Primary specialty name to include.
        required: false
        schema:
          type: string
        example: gastroenterology
      - name: apply_specialty_grouping
        in: query
        description: Whether to group related specialties automatically.
        required: false
        schema:
          type: boolean
        example: false
      - name: procedure_ids
        in: query
        description: Comma-separated list of procedure IDs to include.
        required: false
        schema:
          type: string
        example: 9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae
      - name: _excl_procedure_ids
        in: query
        description: Comma-separated list of procedure IDs to exclude.
        required: false
        schema:
          type: string
        example: 9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae
      - name: procedure
        in: query
        description: Procedure name to include.
        required: false
        schema:
          type: string
        example: MRI, thoracic spine
      - name: min_experience_index
        in: query
        description: Minimum experience index of providers for the given procedure.
        required: false
        schema:
          type: integer
        example: 4
      - name: max_cost_index
        in: query
        description: Maximum allowed cost index for the given procedure.
        required: false
        schema:
          type: integer
        example: 4
      - name: clinical_area
        in: query
        description: Name of the clinical area to filter on.
        required: false
        schema:
          type: string
        example: Mental Health
      - name: clinical_area_ids
        in: query
        description: Comma-separated clinical area IDs to include.
        required: false
        schema:
          type: string
        example: a7da792c-fae3-4b46-bab7-220e0c54e376
      - name: _excl_clinical_area_ids
        in: query
        description: Comma-separated clinical area IDs to exclude.
        required: false
        schema:
          type: string
        example: a7da792c-fae3-4b46-bab7-220e0c54e376
      - name: condition
        in: query
        description: Name of the condition to filter on.
        required: false
        schema:
          type: string
        example: depression
      - name: condition_ids
        in: query
        description: Comma-separated condition IDs to include.
        required: false
        schema:
          type: string
        example: fd7c10f3-fbec-482a-929b-be94a8bb3bc1
      - name: _excl_condition_ids
        in: query
        description: Comma-separated condition IDs to exclude.
        required: false
        schema:
          type: string
        example: fd7c10f3-fbec-482a-929b-be94a8bb3bc1
      - name: treatment
        in: query
        description: Treatment name to filter on.
        required: false
        schema:
          type: string
        example: Psychological Therapy
      - name: treatment_ids
        in: query
        description: Comma-separated treatment IDs to include.
        required: false
        schema:
          type: string
        example: 11016779-e286-4b17-bd45-2d78660a9f28
      - name: _excl_treatment_ids
        in: query
        description: Comma-separated treatment IDs to exclude.
        required: false
        schema:
          type: string
        example: 11016779-e286-4b17-bd45-2d78660a9f28
      - name: panel_ages
        in: query
        description: Comma-separated age panels to include.
        required: false
        schema:
          type: string
          enum:
          - Pediatric (0-12)
          - Adolescent (13-21)
          - Adult (22-44)
          - Adult (45-64)
          - Senior (65 and over)
      - name: _excl_panel_ages
        in: query
        description: Comma-separated age panels to exclude.
        required: false
        schema:
          type: string
          enum:
          - Pediatric (0-12)
          - Adolescent (13-21)
          - Adult (22-44)
          - Adult (45-64)
          - Senior (65 and over)
      - name: panel_sexes
        in: query
        description: Filter for sexes or gender categories (e.g., 'Primarily female').
        required: false
        schema:
          type: string
          enum:
          - Both female and male
          - Primarily female
          - Primarily male
        example: Primarily female
      - name: min_outcomes_index
        in: query
        description: Minimal acceptable outcomes score/index.
        required: false
        schema:
          type: integer
        example: 5
      - name: min_efficiency_index
        in: query
        description: Minimal acceptable efficiency score/index.
        required: false
        schema:
          type: integer
        example: 5
      - name: max_unit_cost_index
        in: query
        description: Maximum allowable unit cost index.
        required: false
        schema:
          type: integer
        example: 10
      - name: max_ribbon_cost_score
        in: query
        description: Maximum allowable "ribbon" cost score.
        required: false
        schema:
          type: integer
        example: 10
      - name: location_organization_ids
        in: query
        description: Comma-separated organization IDs for location matching.
        required: false
        schema:
          type: string
        example: 497a1ac1-52cc-43a9-b796-844dabde10fc
      - name: _excl_location_organization_ids
        in: query
        description: Comma-separated organization IDs to exclude.
        required: false
        schema:
          type: string
        example: 497a1ac1-52cc-43a9-b796-844dabde10fc
      - name: tin_ids
        in: query
        description: Comma-separated TIN IDs to include.
        required: false
        schema:
          type: string
        example: '123456789'
      - name: tin_name
        in: query
        description: TIN name or partial name to include.
        required: false
        schema:
          type: string
        example: Acme TIN
      - name: tin_legal_name
        in: query
        description: TIN's legal name to include.
        required: false
        schema:
          type: string
        example: Acme Legal TIN
      responses:
        '200':
          description: Returns an ordered list of matching providers
          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
                      sort_by:
                        type: string
                        description: The main criteria used to sort results in the record set.
                        example: distance
                      geo:
                        type: object
                        properties:
                          latitude:
                            type: number
                            description: The latitude the search was focused on.
                            example: 40.7351327
                          longitude:
                            type: number
                            description: The longitude the search was focused on.
                            example: -73.9881657
                      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
                      max_locations:
                        type: integer
                        description: The maximum number of locations attached to any given provider. Defaults to 5 (not shown if unspecified).
                        format: int32
                        example: 5
                      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.


                          Cannot be used in tandem with `_excl_fields`'
                        example:
                        - locations
                        - age
                        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.
                        example:
                        - locations
                        - age
                        items:
                          type: string
                      npis:
                        type: array
                        description: 'List of desired NPIs (i.e. use this to search for 5 specific doctors).


                          Note: This parameter cannot be used in combination with any other parameters. All other parameters will be ignored.'
                        example:
                        - 1234567890
                        items:
                          type: string
                      name:
                        type: string
                        description: String input of a full, first, last, or partial name.
                        example: Doe
                      provider_types:
                        type: array
                        description: 'The ''types'' of providers you searched for. Provider types are higher level groupings of specialties. Here are a few key provider types:

                          - Doctor

                          - Nursing

                          - Dental Providers

                          - Optometry

                          - Chiropractic Providers


                          See the Specialties Reference Endpoint for a list of all specialties and their provider types.'
                        example:
                        - Optometry
                        items:
                          type: string
                      gender:
                        type: string
                        description: String input of either m or f to filter to only medical providers of the inputted gender.
                        example: m
                        enum:
                        - m
                        - f
                        x-enum-elements:
                        - name: m
                          description: ''
                        - name: f
                          description: ''
                      max_age:
                        type: integer
                        description: Integer input (i.e. 50) to filter to only medical providers under the inputted age.
                        format: int32
                        example: 70
                      min_age:
                        type: integer
                        description: Integer input (i.e. 50) to filter to only medical providers above the inputted age.
                        format: int32
                        example: 45
                      language:
                        type: object
                        properties:
                          results:
                            type: array
                            description: The languages that matched the given `language` parameter
                            items:
                              type: string
                          value:
                            type: string
                            example: English
                          description: {}
                      min_rating:
                        maximum: 10
                        minimum: 0
                        type: integer
                        description: Integer input (from 0 to 10) to filter to only providers above the inputted value for the ratings_avg field.
                        format: int32
                        example: 6
                      address:
                        type: string
                        description: String input of an address that will be interpreted and geocoded in real time.
                        example: New York, NY
                      location_ids:
                        type: array
                        description: List of desired practice location uuids. See all providers who see patients at any of the given practice locations.
                        example:
                        - 34ecc98a-e49e-49e3-84f9-b0ab2ff00495
                        items:
                          type: string
                          format: uuid
                      min_location_confidence:
                        maximum: 5
                        minimum: 0
                        type: integer
                        description: 'Integer input (0-5) of the minimum confidence threshold for returned provider locations. min_location_confidence=3 will only display providers'' locations that have a confidence 3 or higher. If a provider has a 5 locations, one of which is greater than 3, only the high confidence location will be included in the returned JSON output.


                          Note: when this parameter is in use, the maximum number of records accessible is 1000 (i.e. if you maintain the default page_size of 25, the last page that can be paginated to is 40)'
                        format: int32
                        example: 3
                      min_confidence:
                        maximum: 5
                        minimum: 0
                        type: integer
                        description: Integer input (0-5) of the minimum confidence location you wish the returned providers to have (i.e. min_confidence=4 will only display providers who have a location with confidence 4 or higher). This is a more performant but 'simpler' version of `min_location_confidence` parameter.
                        format: int32
                        example: 3
                      distance:
                        type: integer
                        description: "The proximity radius of providers returned.\n\n Note: When using `min_location_confidence` and `location_insurance_ids` parameters, limit `distance` to be less than 50 miles to ensure high quality results."
                        format: int32
                        example: 10
                      state:
                        type: string
                        description: Two-letter state abbreviation of provider locations to filter to. Note that this parameter will override `address` and `location` parameters if used together.
                        example: NY
                      insurance_ids:
                        type: array
                        description: List of desired insurance uuids. See all providers who accept a given insurance(s).
                        example:
                        - e527f6e3-fe42-4932-bf34-d81f1c1fd652
                        items:
                          type: string
                          format: uuid
                      insurance_carrier_name:
                        type: string
                        description: 'String input of carrier_name in order to search for all providers that take at least one plan from a given insurance carrier.


                          Find the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.


                          Note: This input must be an exact string match to work'
                        example: Aetna
                      location_insurance_ids:
                        type: array
                        description: 'List of desired insurance uuids. See all provider locations that accept a given insurance(s).


                          Note, this parameter cannot be combined with `insurance_ids` to filter on provider insurances and provider location insurances.'
                        example:
                        - 34ecc98a-e49e-49e3-84f9-b0ab2ff00495
                        items:
                          type: string
                          format: uuid
                      national_bluecard:
                        type: boolean
                        description: Boolean input that enables an API search to automatically default to the National BlueCard EPO/PPO Network whenever a member searches for out-of-state, in-network care and is covered by a BCBS Association PPO insurance plan. Use the parameter in conjunction with the address parameter and either the insurance_ids or insurance fuzzy search parameters. Defaults to true unless otherwise specified.
                        example: true
                      specialty_ids:
                        type: array
                        description: 'List of desired specialty uuids. See all providers who specialize in the given specialties.


                          Cannot be used in tandem with `specialty_ids_primary` or `specialty_primary`.'
                        example:
                        - 1de33770-eb1c-47fa-ab3e-f9a4ab924d9d
                        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
                      specialty_ids_primary:
                        type: array
                        description: 'List of specialty uuids. See all providers whose primary specialties are in the given specialties.


                          Cannot be used in tandem with `specialty_ids` or `specialty`.'
                        example:
                        - 1de33770-eb1c-47fa-ab3e-f9a4ab924d9d
                        items:
                          type: string
                          format: uuid
                      primary_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
   

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