{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "getCustomLocations", "description": "JSON Schema for getCustomLocations response from Ribbon Health H1 API", "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.\n\nCannot 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.\nSee 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.\nFind the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.\nNote: 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", "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 } } } } } }, "clinical_area_ids": { "type": "array", "description": "List of desired clinical area ids.\nReturns all locations with a clinical area exactly matching any of the entered IDs.\n(Note: Use the `/clinical_areas/` reference endpoint to identify relevant IDs)", "example": [ "4c03ddb4-f6c0-4574-a51e-508f83c43d69" ], "items": { "type": "string" } }, "treatment": { "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 } } } } } }, "treatment_ids": { "type": "array", "description": "List of desired treatment ids.\nReturns all providers with a `treatments.uuid` field exactly matching any of the entered IDs.\n(Note: Use the /treatments/ reference endpoint (docs) to identify relevant IDs)", "example": [ "e3079513-bf55-41cc-87c6-f7ff5f923085" ], "items": { "type": "string" } }, "tin_ids": { "type": "string", "description": "List of desired TINs." }, "tin_name": { "type": "string" }, "tin_legal_name": { "type": "string" } } }, "data": { "type": "array", "description": "", "items": { "type": "object", "properties": { "distance": { "type": "number", "description": "This location's distance from the center of a geographic search, in miles.", "example": 0.4 }, "uuid": { "type": "string", "description": "A UUID uniquely identifying this location", "format": "uuid", "example": "f38b9fd5-1e28-4f6e-953c-1e1493b68e21" }, "name": { "type": "string", "nullable": true }, "address": { "type": "string", "example": "185 Berry St # 130, San Francisco, CA 94107, US" }, "address_details": { "type": "object", "properties": { "street": { "type": "string", "example": "185 Berry St # 130" }, "address_line_1": { "type": "string", "example": "185 Berry St" }, "address_line_2": { "type": "string", "nullable": true, "example": "# 130" }, "city": { "type": "string", "example": "San Francisco" }, "state": { "type": "string", "example": "CA" }, "zip": { "type": "string", "example": "94107" } } }, "latitude": { "type": "number", "example": 37.7765973 }, "longitude": { "type": "number", "example": -122.3919488 }, "google_maps_link": { "type": "string", "example": "https://www.google.com/maps/@37.7765973-122.3919488?q=185%20Berry%20St%20%23%20130%2C%20SF%2C%20CA%2094107%2C%20US" }, "phone_numbers": { "type": "array", "description": "", "items": { "type": "object", "properties": { "phone": { "type": "string", "example": "4155146410" }, "details": { "type": "string", "example": "primary" } } } }, "faxes": { "type": "array", "description": "Fax numbers associated with this location.\n\nThis property only appears for customers purchasing fax data. If you would like this property and are not receiving it, please reach out to support.", "items": { "type": "object", "properties": { "phone": { "type": "string", "example": "2121234567" }, "details": { "type": "string", "example": "secondary" }, "confidence": { "type": "integer", "format": "int32", "example": 3 } } } }, "confidence": { "type": "integer", "description": "Each location contains a confidence score. This score indicates the probability of the given provider practicing at said location with the included contact information\n\nThis field will only be populated for Ribbon-provided locations. Locations you create yourself will have a confidence score of `null`.", "format": "int32", "nullable": true, "example": 2 }, "insurances": { "type": "array", "description": "List of insurances the accepted at this location", "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" } } ] } } } } }, "tins": { "type": "string", "description": "Comma separated list of standard 9-digit identification code(s) used by the IRS for business entities and used for contracting and paying provider/facility claims." } } } } } }