--- updatedAt: 2026-06-05T13:06:03.000Z agentTools: projectIndex: https://ribbon.readme.io/llms.txt --- # Search Conditions Returns conditions that exist within the Ribbon API. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "H1's API", "version": "1.0.0", "description": "An API for interacting with the data provided by Ribbon Health, including information about healthcare providers,\nlocations, insurances, and more.\n\n## Price Transparency v2\n\nLocation-first negotiated rate endpoints live under `/v2/*` (separate from legacy\n`/v1/pricing/*`). Use them to:\n\n1. Look up procedures, care clusters, and carriers (`GET /v2/procedures`,\n `/v2/care-clusters`, `/v2/carriers`)\n2. Get prices for a known location (`GET /v2/locations/{location_id}/pricing/...`)\n3. Shop by geography (`GET /v2/pricing/locations/...`)\n\n**Key differences from v1:** prices are location-scoped (not provider-first);\ncarriers use string business ids (not v1 carrier UUIDs); every v2 response uses\nthe same envelope (`parameters`, `total_count`, `page`, `page_size`, `data`);\ngeo search requires an explicit `address` or `lat`+`lng` (no silent default).\n\nSee the **Price Transparency v2** tag for full endpoint reference.\n" }, "servers": [ { "url": "https://api.ribbonhealth.com" } ], "tags": [ { "name": "Price Transparency v2", "description": "Location-first negotiated rates under `/v2/*`. Prefer these endpoints for new\nintegrations. Carrier ids come from `GET /v2/carriers` and are not interchangeable\nwith v1 pricing carrier UUIDs. Provider-scoped v2 routes are not live yet.\n" } ], "paths": { "/v1/custom/conditions": { "get": { "summary": "Search Conditions", "description": "Returns conditions that exist within the Ribbon API.\n", "operationId": "getConditions", "tags": [ "Focus Area Endpoints" ], "parameters": [ { "name": "Condition Search Parameters", "in": "query", "required": false, "description": "Search parameters for the condition endpoint.", "explode": true, "schema": { "type": "object", "properties": { "page": { "type": "integer", "example": 1, "description": "The page of the results which was returned." }, "page_size": { "type": "integer", "example": 25, "description": "How many results are in each page." }, "search": { "type": "string", "description": "String input that fuzzy searches against key fields within each condition object to return the most relevant options.\n", "example": "depression" }, "_excl_condition_ids": { "type": "string", "example": "2938baf9-f064-44d6-8251-6e4b9fbb6fd2,c9d21735-8a78-45fe-982b-d216cb94beb7", "description": "Comma separated list of condition UUIDs to exclude from search results." }, "specialty_ids": { "type": "string", "example": "fcc9a22c-7a0f-4405-b0c9-c5f8ad83b93e,8b5d3998-d7e2-4b9e-91d1-17c19cd089f5", "description": "Comma separated list of specialty UUIDs." }, "module": { "type": "string", "example": "focus_areas", "description": "String input of the type of clinical areas to return. Options for input are either `focus_areas` or `condition_cost_estimate`.\nNote: This input must be an exact string match to work\n" } } } } ], "responses": { "200": { "description": "Conditions returned from a valid request", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "parameters", "results" ], "properties": { "count": { "type": "integer", "description": "The total number of results matched, across all pages.", "example": 480 }, "next": { "type": [ "string", "null" ], "example": "https://api.ribbonhealth.com/v1/custom/conditions?page=3" }, "previous": { "type": [ "string", "null" ], "example": "https://api.ribbonhealth.com/v1/custom/conditions?page=1" }, "parameters": [ { "$ref": "#/paths/~1v1~1custom~1conditions/get/parameters/0" } ], "results": { "type": "array", "items": { "$ref": "#/paths/~1v1~1custom~1conditions~1%7Bcondition_uuid%7D/get/responses/200/content/application~1json/schema" } } } } } } }, "400": { "description": "Module does not exist", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema" } } } } } } }, "/v2/carriers": { "get": { "summary": "List Carriers (v2)", "description": "List carriers available in the Price Transparency v2 pricing data set.\n\nUse this to discover valid `carrier_id` values for pricing filters.\n\n#### Important\nThese identifiers are **not** the same as v1 [`/v1/pricing/carriers`](./getpricingcarriers)\nUUIDs. Always resolve carriers through this endpoint (or a curated customer\nmapping) when working with v2.\n", "operationId": "getV2Carriers", "tags": [ "Price Transparency v2" ], "parameters": [ { "name": "carrier_id", "in": "query", "required": false, "description": "Exact match on carrier business id.", "schema": { "type": "string", "example": "78110" } }, { "name": "carrier_name", "in": "query", "required": false, "description": "Match on carrier display name. Case-insensitive substring on\n`/v2/carriers`; case-insensitive exact match on DB-backed pricing endpoints;\ncase-sensitive exact match on Elasticsearch search endpoints.\n", "schema": { "type": "string", "example": "Aetna" } }, { "name": "page", "in": "query", "required": false, "description": "Page of results to return. Values below `1` are treated as `1`.\n", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of results per page. Hard-capped at **100**.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 20 } } ], "responses": { "200": { "description": "Matching carriers.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Standard response envelope for all Price Transparency v2 endpoints.\nPagination fields are always present; `parameters` echoes the non-null filters\nthat were applied (pagination keys are omitted from the echo).\n", "required": [ "parameters", "total_count", "page", "page_size", "data" ], "properties": { "parameters": { "type": "object", "additionalProperties": true, "description": "Echo of non-null request filters (pagination omitted).", "example": { "code": "27447", "code_scheme": "CPT" } }, "total_count": { "type": "integer", "description": "Total matching rows across all pages.", "example": 1 }, "page": { "type": "integer", "description": "Current page number.", "example": 1 }, "page_size": { "type": "integer", "description": "Page size used for this response.", "example": 20 }, "data": { "type": "array", "description": "Records for the current page.", "items": {} } } }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "An insurance carrier in the Price Transparency v2 data set.\nUse `carrier_id` as the filter value on pricing endpoints.\n", "required": [ "carrier_id", "name" ], "properties": { "carrier_id": { "type": "string", "description": "Business id used in all v2 pricing filters.", "example": "78110" }, "name": { "type": "string", "description": "Display name.", "example": "Aetna" } } }, "example": [ { "carrier_id": "78110", "name": "Aetna" } ] } } } ] }, "example": { "parameters": { "carrier_name": "aetna" }, "total_count": 1, "page": 1, "page_size": 20, "data": [ { "carrier_id": "78110", "name": "Aetna" } ] } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "description": "An error returned from the API", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "integer", "description": "The HTTP error code associated with this error", "example": 400 }, "code": { "type": "string", "enum": [ "invalid_query_params", "bad_request" ] }, "message": { "type": [ "object", "string" ], "description": "An object representing what exactly went wrong. The keys available in this object vary with the type of error returned.\n", "example": { "query": { "_schema": [ "parameters 'npis' and 'location_ids' cannot be used together" ] } } } } } } } } } }, "403": { "description": "The caller does not have Price Transparency access.", "content": { "application/json": { "schema": { "type": "object", "description": "You are not allow to make this request", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "enum": [ "permission_denied" ] }, "message": { "type": "string", "example": "a trial account does not have access to this functionality" } } } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ] } ```