Ribbon Health Locations API

openapi: 3.0.0
info:
  title: ribbon-health Cost Estimates Locations 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: Locations
  description: ''
paths:
  /custom/locations:
    get:
      tags:
      - Locations
      summary: getCustomLocations
      description: 'Allows you to search for different service locations, including specific location types.

        '
      operationId: getCustomLocations
      parameters:
      - name: page
        in: query
        required: false
        description: The page of the results which was returned.
        schema:
          type: integer
          format: int32
        example: 1
      - name: page_size
        in: query
        required: false
        description: How many results are in each page.
        schema:
          type: integer
          format: int32
        example: 25
      - name: fields
        in: query
        required: false
        description: 'Comma separated list of fields within the location 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`'
        schema:
          type: string
        example: name,address
      - name: _excl_fields
        in: query
        required: false
        description: Comma separated list of fields within the location 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.
        schema:
          type: string
        example: phone_numbers,insurances
      - name: address
        in: query
        required: false
        description: String input of an address that will be interpreted and geocoded in real time.
        schema:
          type: string
        example: New York, NY
      - name: name
        in: query
        required: false
        description: String input for a 'fuzzy' search on location name.
        schema:
          type: string
        example: Citymd Urgent Care
      - name: distance
        in: query
        required: false
        description: The proximity radius of locations returned.
        schema:
          type: integer
          format: int32
        example: 10
      - name: location_types
        in: query
        required: false
        description: 'Comma separated list of values that filter to what type of facilities to show. We categorize locations into 36 types. Clients can add their own locations with unique location_types, and they will also be included in the search.

          See the Location Types Reference Endpoint for a list of all location types.'
        schema:
          type: string
        example: Urgent Care
      - name: _excl_location_types
        in: query
        required: false
        description: Comma separated list of the 'types' of locations to exclude. Excludes locations with a matching location type.
        schema:
          type: string
        example: Urgent Care
      - name: location
        in: query
        required: false
        description: Latitude/longitude pair of coordinates in lieu of a string address.
        schema:
          type: string
        example: 37.7489816,-122.4802092
      - name: location_ids
        in: query
        required: false
        description: Comma separated list of desired practice location uuids.
        schema:
          type: string
        example: 48d4eb27-d82b-4ea4-8ad0-4bcb2c46a960
      - name: _excl_location_ids
        in: query
        required: false
        description: Comma separated list of practice location uuids to exclude.
        schema:
          type: string
        example: 48d4eb27-d82b-4ea4-8ad0-4bcb2c46a960
      - name: insurance_ids
        in: query
        required: false
        description: Comma separated list of desired insurance uuids. See all locations that accept a given insurance(s).
        schema:
          type: string
        example: 24617022-92b3-4b9f-af1c-4df21ad6fb6f
      - name: _excl_insurance_ids
        in: query
        required: false
        description: Comma separated list of insurance uuids to exclude. Exclude locations that accept a given insurance(s).
        schema:
          type: string
        example: 24617022-92b3-4b9f-af1c-4df21ad6fb6f
      - name: insurance_carrier_name
        in: query
        required: false
        description: 'String input of carrier_name in order to search for all locations 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'
        schema:
          type: string
        example: Aetna
      - name: min_confidence
        in: query
        required: false
        description: Integer input (0-5) of the minimum confidence threshold for returned locations. min_location_confidence=4 will only display locations that have a confidence 4 or higher.
        schema:
          type: integer
          format: int32
      - name: national_bluecard
        in: query
        required: false
        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.
        schema:
          type: boolean
        example: true
      - name: organization_ids
        in: query
        required: false
        description: Comma separated list of desired organization uuids. Filters to only locations that are affiliated with the given organization uuid(s).
        schema:
          type: string
        example: 86722ebb-1dd1-4846-a1a9-a7a9e36c944d
      - name: _excl_organization_ids
        in: query
        required: false
        description: Comma separated list of organization uuids to exclude. Excludes locations that are affiliated with the given organization uuid(s).
        schema:
          type: string
        example: 86722ebb-1dd1-4846-a1a9-a7a9e36c944d
      - name: clinical_area
        in: query
        required: false
        description: 'String input that is fuzzy matched to the most relevant `clinical_area.display` field. Only a single clinical area will be selected.

          Returns all location with this clinical area.'
        schema:
          type: string
        example: CT
      - name: clinical_area_ids
        in: query
        required: false
        description: 'Comma-separated list of desired clinical area ids.

          Returns all locations with a clinical area exactly matching any of the entered IDs.

          (Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)'
        schema:
          type: string
        example: 4c03ddb4-f6c0-4574-a51e-508f83c43d69
      - name: _excl_clinical_area_ids
        in: query
        required: false
        description: 'Comma-separated list of clinical area ids to exclude.

          Returns all locations without a clinical area exactly matching any of the entered IDs.

          (Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)'
        schema:
          type: string
        example: 4c03ddb4-f6c0-4574-a51e-508f83c43d69
      - name: treatment
        in: query
        required: false
        description: 'String input that is fuzzy matched to the most relevant `treatments.display` field. Only a single treatment will be selected.

          Returns all locations with this treatment.'
        schema:
          type: string
        example: Neck X-ray
      - name: treatment_ids
        in: query
        required: false
        description: 'Comma-separated list of desired treatment ids.

          Returns all locations with a `treatments.uuid` field exactly matching any of the entered IDs.

          (Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)'
        schema:
          type: string
        example: e3079513-bf55-41cc-87c6-f7ff5f923085
      - name: _excl_treatment_ids
        in: query
        required: false
        description: 'Comma-separated list of treatment ids to exclude.

          Returns all locations without a `treatments.uuid` field exactly matching any of the entered IDs.

          (Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)'
        schema:
          type: string
        example: e3079513-bf55-41cc-87c6-f7ff5f923085
      - name: tin_ids
        in: query
        required: false
        description: 'Comma separated list of desired TINs. Filters to only locations that are affiliated with the given TINs.

          Note: This parameter cannot be used in combination with any other TINs related parameters. All other TINs related parameters will be ignored.'
        schema:
          type: string
      - name: tin_name
        in: query
        required: false
        description: String input that is fuzzy matched against the `tins.name` field. Filters to only locations that are affiliated with the given TINs name.
        schema:
          type: string
      - name: tin_legal_name
        in: query
        required: false
        description: String input that is fuzzy matched against the `tins.legal_name` field. Filters to only locations that are affiliated with the given TINs legal name.
        schema:
          type: string
      responses:
        '200':
          description: Returns an ordered list of matching locations
          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
                      fields:
                        type: array
                        description: 'List of fields within the location 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 location 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
                      address:
                        type: string
                        description: String input of an address that will be interpreted and geocoded in real time.
                        example: New York, NY
                      name:
                        type: string
                        description: String input for a fuzzy search on location name.
                        example: Citymd Urgent Care
                      distance:
                        type: integer
                        description: The proximity radius of locations returned.
                        format: int32
                        example: 10
                      location_types:
                        type: array
                        description: 'List of values that filter to what type of facilities to show. We categorize locations into 34 types. Clients can add their own locations with unique location_types, and they will also be included in the search.

                          See the Location Types Reference Endpoint for a list of all location types.'
                        example:
                        - Urgent Care
                        items:
                          type: string
                      _excl_location_types:
                        type: array
                        description: List of the 'types' of locations to exclude. Excludes locations with a matching location type.
                        example:
                        - Urgent Care
                        items:
                          type: string
                      insurance_ids:
                        type: array
                        description: List of desired insurance uuids. See all locations that accept a given insurance(s).
                        example:
                        - e527f6e3-fe42-4932-bf34-d81f1c1fd652
                        items:
                          type: string
                          format: uuid
                      _excl_insurance_ids:
                        type: array
                        description: List of insurance uuids to exclude. Exclude locations that 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 locations 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
                      min_confidence:
                        maximum: 5
                        minimum: 0
                        type: integer
                        description: Integer input (0-5) of the minimum confidence threshold for returned locations. min_location_confidence=4 will only display locations that have a confidence 4 or higher.
                        format: int32
                      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
                      organization_ids:
                        type: array
                        description: Comma separated list of desired organization uuids. Filters to only locations that are affiliated with the given organization uuid(s).
                        example:
                        - 86722ebb-1dd1-4846-a1a9-a7a9e36c944d
                        items:
                          type: string
                      _excl_organization_ids:
                        type: array
                        description: Comma separated list of organization uuids to exclude. Excludes locations that are affiliated with the given organization uuid(s).
                        example:
                        - 86722ebb-1dd1-4846-a1a9-a7a9e36c944d
                        items:
                          type: string
                      clinical_area:
                        type: object
                        properties:
                          uuid:
                            type: string
                            description: A UUID uniquely identifying this clinical area
                            format: uuid
                            example: f352b596-dfb0-494f-9a03-224794f5d182
                          display:
                            type: string
                            example: Substance Disorders (e.g. Opioid, Cocaine, Alcohol)
                          types:
                            type: array
                            description: ''
                            items:
                              type: string
                              enum:
                              - providers
                              - locations
                              x-enum-elements:
                              - name: providers
                                description: ''
                              - name: locations
                                description: ''
                          conditions:
                            type: array
                            description: ''
                            items:
                              type: object
                              properties:
                                uuid:
                                  type: string
                                  description: A UUID uniquely identifying this condition
                                  format: uuid
                                  example: 99f4762e-c4c2-4d1d-983a-2b8b303e691d
                                display:
                                  type: string
                                  example: Chronic Depression
                                types:
                                  type: array
                                  description: ''
                                  items:
                                    type: string
                                    enum:
                                    - focus_areas
                                    - condition_cost_estimate
                                    x-enum-elements:
                                    - name: focus_areas
                                      description: ''
                                    - name: condition_cost_estimate
                                      description: ''
                                specialties:
                                  type: array
                                  description: ''
                                  items:
                                    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
                                modules:
                                  type: array
                                  description: ''
                                  items:
                                    type: string
                          treatments:
                            type: array
                            description: ''
                            items:
                              type: object
                              properties:
                                uuid:
                                  type: string
                                  description: A UUID uniquely identifying this treatment
                                  format: uuid
                                  example: 88a70b34-d0a7-47e2-89ac-4fed203eca2f
                                display:
                                  type: string
                                  example: Knee Replacement
                                types:
                                  type: array
                                  description: ''
                                  items:
                                    type: string
                                    enum:
                                    - providers
                                    - locations
                                    x-enum-elements:
                                    - name: providers
                                      description: ''
                                    - name: locations
                                      description: ''
                                specialties:
                                  type: array
                                  description: ''
                                  items:
                                    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
                          specialties:
                            type: array
                            description: ''
                            items:
                              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
              

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