Ribbon Health · Schema
getCustomProviders
JSON Schema for getCustomProviders response from Ribbon Health H1 API
HealthcareProvider DirectoryInsuranceClinical DataCare NavigationEligibilityPrice TransparencyProvider SearchHealth PlansDigital Health
Properties
| Name | Type | Description |
|---|---|---|
| parameters | object | |
| data | array |
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "getCustomProviders",
"description": "JSON Schema for getCustomProviders 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
},
"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.\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 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).\n\nNote: 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:\n- Doctor\n- Nursing\n- Dental Providers\n- Optometry\n- Chiropractic Providers\n\nSee 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.\n\nNote: 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.\n\nFind the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.\n\nNote: 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).\n\nNote, 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.\n\nCannot 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.\n\nCannot 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",
"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
}
}
},
"apply_specialty_grouping": {
"type": "boolean",
"description": "Boolean input that enables an API search to automatically default to apply the inclusions and exclusions logic for grouping relevant specialties when using the `specialty` or `specialty_primary` parameter. Defaults to `true`.\nFor details, please read [our guide on searching by specialties](https://ribbon.readme.io/docs/search-for-specialties).",
"example": false
},
"procedure_ids": {
"type": "array",
"description": "Comma separated list of desired procedure uuids. Filter to only providers who perform the given procedure.",
"example": [
"9f3fd9e8-96b0-4cc7-ab2c-8d538e9164ae"
],
"items": {
"type": "string",
"format": "uuid"
}
},
"procedure": {
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "A UUID uniquely identifying this procedure",
"format": "uuid",
"example": "0a9a245f-2f52-4cc0-a5c3-77a811acc6f7"
},
"display": {
"type": "string",
"example": "MRI, arm"
},
"procedure_code_count": {
"type": "integer",
"format": "int32",
"example": 7
},
"procedure_codes": {
"type": "array",
"description": "",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"example": "73222"
},
"type": {
"type": "string",
"example": "CPT"
},
"description": {
"type": "string",
"example": "MRI, arm"
}
}
}
}
}
},
"min_experience_index": {
"description": "Float input of the minimum experience index for procedures. min_experience_index=4 will only return providers that have an experience index of 4 or higher for at least one of the given procedure uuids.\n\nNote: This parameter must be used with `procedure_ids`.",
"example": 4
},
"max_cost_index": {
"description": "Float input of the maximum cost index for procedures. max_cost_index=4 will only return providers that have a cost index of 4 or less for at least one of the given procedure uuids.\n\nNote: This parameter must be used with `procedure_ids`.",
"example": 4
},
"clinical_area": {
"type": "string",
"description": "String input that is fuzzy matched to the most relevant `clinical_area.display` field. Only a single clinical area will be selected.\n\nReturns all providers with this clinical area.",
"example": "Mental Health"
},
"clinical_area_ids": {
"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
}
}
}
}
}
},
"condition": {
"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": [
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ribbon-health/refs/heads/main/json-schema/getcustomproviders.json