{ "openapi": "3.1.0", "info": { "title": "Turquoise Health Consumer Pricing API v3", "version": "0.1.0" }, "paths": { "/v3/providers/types": { "get": { "tags": [ "Consumer Pricing" ], "summary": "Get Provider Types", "description": "Fetch provider types. Results return valid inputs to filter by provider types across the API.", "operationId": "v3_get_provider_types", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "type": "string" }, "type": "array", "title": "Response V3 Get Provider Types" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/providers": { "get": { "tags": [ "Consumer Pricing" ], "summary": "List Providers", "description": "Retrieve a list of providers, filtered over a search by name, NPI, provider type, or location. Additionally, filter to a list of providers with Turquoise price estimates available by a selected payer, network, or package. Results reflect provider, payer, and package combinations that Turquoise has priced services for; the list may not be comprehensive of all contacted payer networks or services that are available.", "operationId": "v3_list_providers", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive substring match on provider name.", "examples": [ "Intermountain Health Saint Joseph Hospital" ], "title": "Name" }, "description": "Case-insensitive substring match on provider name." }, { "name": "npi", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact NPI match.", "examples": [ "1417946021" ], "title": "Npi" }, "description": "Exact NPI match." }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provider type as reported in the dataset (exact match).", "examples": [ "Short Term Acute Care Hospital" ], "title": "Type" }, "description": "Provider type as reported in the dataset (exact match)." }, { "name": "package_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Providers with at least one price for this package.", "examples": [ "OB002" ], "title": "Package Id" }, "description": "Providers with at least one price for this package." }, { "name": "network_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Providers with at least one price under this network (combined with package_id/payer_id, the same price row must match).", "examples": [ "-3776001016975145508" ], "title": "Network Id" }, "description": "Providers with at least one price under this network (combined with package_id/payer_id, the same price row must match)." }, { "name": "payer_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Providers priced under any of this payer's networks (combined with other relationship filters, the same price row must match).", "examples": [ "76" ], "title": "Payer Id" }, "description": "Providers priced under any of this payer's networks (combined with other relationship filters, the same price row must match)." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Semantic search over provider names. Composes with the other filters and a near/zip location; returns a single relevance-ordered page. 503 search_unavailable until the provider embedding index is populated.", "examples": [ "Saint Joseph hospital in Denver" ], "title": "Search" }, "description": "Semantic search over provider names. Composes with the other filters and a near/zip location; returns a single relevance-ordered page. 503 search_unavailable until the provider embedding index is populated." }, { "name": "min_score", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "description": "Minimum similarity score (0-1).", "title": "Min Score" }, "description": "Minimum similarity score (0-1)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 250, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from a previous page.next_cursor.", "title": "Cursor" }, "description": "Opaque cursor from a previous page.next_cursor." }, { "name": "location.near.lat", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "examples": [ 39.745961 ], "title": "Location.Near.Lat" } }, { "name": "location.near.lng", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "examples": [ -104.971559 ], "title": "Location.Near.Lng" } }, { "name": "location.near.radius_m", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "examples": [ 25000 ], "title": "Location.Near.Radius M" } }, { "name": "location.within.state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "examples": [ "CO" ], "title": "Location.Within.State" } }, { "name": "location.within.cbsa", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Denver-Aurora-Centennial, CO" ], "title": "Location.Within.Cbsa" } }, { "name": "location.within.zip_codes", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated ZIP codes (exact match, any-of).", "examples": [ "80218,80210" ], "title": "Location.Within.Zip Codes" }, "description": "Comma-separated ZIP codes (exact match, any-of)." }, { "name": "location.zip", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolves the ZIP to its centroid, then runs `near` with the default radius.", "examples": [ "80218" ], "title": "Location.Zip" }, "description": "Resolves the ZIP to its centroid, then runs `near` with the default radius." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_Provider_" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/providers/{provider_id}": { "get": { "tags": [ "Consumer Pricing" ], "summary": "Get Provider Details", "description": "Fetch details for a single provider by provider ID.", "operationId": "v3_get_provider", "parameters": [ { "name": "provider_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Provider identifier.", "examples": [ "5756" ], "title": "Provider Id" }, "description": "Provider identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/payers": { "get": { "tags": [ "Consumer Pricing" ], "summary": "List Payers", "description": "Retrieve a list of payers, filtered over a search by name, location for care, or specific providers and services priced in the Turquoise data. Location scopes to payers with at least one price at an in-area provider. Results reflect provider, payer, and package combinations that Turquoise has priced services for; the list may not be comprehensive of all contracted providers or services that are available.", "operationId": "v3_list_payers", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive substring match on payer name.", "examples": [ "Cigna", "Blue Cross" ], "title": "Name" }, "description": "Case-insensitive substring match on payer name." }, { "name": "provider_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payers with at least one price at this provider.", "examples": [ "5756" ], "title": "Provider Id" }, "description": "Payers with at least one price at this provider." }, { "name": "package_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Payers with at least one price for this package.", "examples": [ "OB002" ], "title": "Package Id" }, "description": "Payers with at least one price for this package." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 250, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from a previous page.next_cursor.", "title": "Cursor" }, "description": "Opaque cursor from a previous page.next_cursor." }, { "name": "location.near.lat", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "examples": [ 39.745961 ], "title": "Location.Near.Lat" } }, { "name": "location.near.lng", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "examples": [ -104.971559 ], "title": "Location.Near.Lng" } }, { "name": "location.near.radius_m", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "examples": [ 25000 ], "title": "Location.Near.Radius M" } }, { "name": "location.within.state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "examples": [ "CO" ], "title": "Location.Within.State" } }, { "name": "location.within.cbsa", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Denver-Aurora-Centennial, CO" ], "title": "Location.Within.Cbsa" } }, { "name": "location.within.zip_codes", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated ZIP codes (exact match, any-of).", "examples": [ "80218,80210" ], "title": "Location.Within.Zip Codes" }, "description": "Comma-separated ZIP codes (exact match, any-of)." }, { "name": "location.zip", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolves the ZIP to its centroid, then runs `near` with the default radius.", "examples": [ "80218" ], "title": "Location.Zip" }, "description": "Resolves the ZIP to its centroid, then runs `near` with the default radius." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_Payer_" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/payers/{payer_id}": { "get": { "tags": [ "Consumer Pricing" ], "summary": "Get Payer Details", "description": "Fetch details about a single payer by payer ID.", "operationId": "v3_get_payer", "parameters": [ { "name": "payer_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Payer identifier.", "examples": [ "76" ], "title": "Payer Id" }, "description": "Payer identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/networks": { "get": { "tags": [ "Consumer Pricing" ], "summary": "List Networks", "description": "Retrieve a list of payer networks, filtered over a search by name, payer organization (e.g., Cigna), location for care, or specific providers and services priced in the Turquoise data. Location scopes to payer networks with at least one price at an in-area provider. Results reflect provider, payer network, and package combinations that Turquoise has priced services for; the list may not be comprehensive of all contracted providers or services that are available.", "operationId": "v3_list_networks", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive substring match on network or payer name.", "examples": [ "Cigna", "National OAP" ], "title": "Name" }, "description": "Case-insensitive substring match on network or payer name." }, { "name": "payer_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact payer id match.", "examples": [ "76" ], "title": "Payer Id" }, "description": "Exact payer id match." }, { "name": "provider_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Networks with at least one price at this provider.", "examples": [ "5756" ], "title": "Provider Id" }, "description": "Networks with at least one price at this provider." }, { "name": "package_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Networks with at least one price for this package.", "examples": [ "OB002" ], "title": "Package Id" }, "description": "Networks with at least one price for this package." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Semantic search over network and payer names. Composes with the other filters; returns a single relevance-ordered page (no cursor).", "examples": [ "Cigna" ], "title": "Search" }, "description": "Semantic search over network and payer names. Composes with the other filters; returns a single relevance-ordered page (no cursor)." }, { "name": "min_score", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "description": "Minimum similarity score (0-1).", "title": "Min Score" }, "description": "Minimum similarity score (0-1)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 250, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from a previous page.next_cursor.", "title": "Cursor" }, "description": "Opaque cursor from a previous page.next_cursor." }, { "name": "location.near.lat", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "examples": [ 39.745961 ], "title": "Location.Near.Lat" } }, { "name": "location.near.lng", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "examples": [ -104.971559 ], "title": "Location.Near.Lng" } }, { "name": "location.near.radius_m", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "examples": [ 25000 ], "title": "Location.Near.Radius M" } }, { "name": "location.within.state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2 }, { "type": "null" } ], "examples": [ "CO" ], "title": "Location.Within.State" } }, { "name": "location.within.cbsa", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "examples": [ "Denver-Aurora-Centennial, CO" ], "title": "Location.Within.Cbsa" } }, { "name": "location.within.zip_codes", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated ZIP codes (exact match, any-of).", "examples": [ "80218,80210" ], "title": "Location.Within.Zip Codes" }, "description": "Comma-separated ZIP codes (exact match, any-of)." }, { "name": "location.zip", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolves the ZIP to its centroid, then runs `near` with the default radius.", "examples": [ "80218" ], "title": "Location.Zip" }, "description": "Resolves the ZIP to its centroid, then runs `near` with the default radius." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_Network_" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/networks/{network_id}": { "get": { "tags": [ "Consumer Pricing" ], "summary": "Get Network Details", "description": "Fetch details about a single network by network ID.", "operationId": "v3_get_network", "parameters": [ { "name": "network_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Network identifier (string-wrapped 64-bit integer).", "examples": [ "-3776001016975145508" ], "title": "Network Id" }, "description": "Network identifier (string-wrapped 64-bit integer)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Network" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/packages": { "get": { "tags": [ "Consumer Pricing" ], "summary": "List Packages", "description": "Return a list of service packages, filtered over name or anchor code. Additionally, filter to a list of packages with Turquoise price estimates available by a selected payer, network, or provider. Results reflect provider, payer, and package combinations that Turquoise has priced services for; the list may not be comprehensive of all payer networks or providers that support this service. When multiple relationship filters are combined, they must be satisfied by the same price row, so results are always fulfillable via GET /v3/prices.", "operationId": "v3_list_packages", "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Case-insensitive substring match on package name.", "examples": [ "delivery" ], "title": "Name" }, "description": "Case-insensitive substring match on package name." }, { "name": "anchor_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Billing code lookup; matches against anchor_codes[].code (package base codes only). Returns every package anchored by the code \u2014 exactly one in the current catalog, but uniqueness is not contractual (an anchor's full upstream identity includes revenue code and billing class, which this API collapses).", "examples": [ "59510" ], "title": "Anchor Code" }, "description": "Billing code lookup; matches against anchor_codes[].code (package base codes only). Returns every package anchored by the code \u2014 exactly one in the current catalog, but uniqueness is not contractual (an anchor's full upstream identity includes revenue code and billing class, which this API collapses)." }, { "name": "provider_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Packages priced at this provider.", "examples": [ "5756" ], "title": "Provider Id" }, "description": "Packages priced at this provider." }, { "name": "network_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Packages with at least one price under this network (combined with provider_id/payer_id, the same price row must match).", "examples": [ "-3776001016975145508" ], "title": "Network Id" }, "description": "Packages with at least one price under this network (combined with provider_id/payer_id, the same price row must match)." }, { "name": "payer_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Packages priced under any of this payer's networks (combined with other relationship filters, the same price row must match).", "examples": [ "76" ], "title": "Payer Id" }, "description": "Packages priced under any of this payer's networks (combined with other relationship filters, the same price row must match)." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Semantic search over package name and description. Composes with the other filters; returns a single relevance-ordered page (no cursor). 503 search_unavailable when the embedding index is not populated.", "examples": [ "cesarean delivery" ], "title": "Search" }, "description": "Semantic search over package name and description. Composes with the other filters; returns a single relevance-ordered page (no cursor). 503 search_unavailable when the embedding index is not populated." }, { "name": "min_score", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "description": "Minimum similarity score (0-1).", "title": "Min Score" }, "description": "Minimum similarity score (0-1)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 250, "minimum": 1, "default": 25, "title": "Page Size" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from a previous page.next_cursor.", "title": "Cursor" }, "description": "Opaque cursor from a previous page.next_cursor." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_Package_" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/packages/{package_id}": { "get": { "tags": [ "Consumer Pricing" ], "summary": "Get Package Details", "description": "Fetch package details by package ID.", "operationId": "v3_get_package", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Package identifier.", "examples": [ "OB002", "RA005", "GA003" ], "title": "Package Id" }, "description": "Package identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Package" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/packages/{package_id}/line_items": { "get": { "tags": [ "Consumer Pricing" ], "summary": "List a Package's Contents", "description": "Review a service package's composition. This includes common codes and fee types, and association rates across variations of packages for a given service.", "operationId": "v3_list_package_line_items", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Package identifier.", "examples": [ "OB002", "RA005", "GA003" ], "title": "Package Id" }, "description": "Package identifier." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_LineItem_" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/prices/query": { "post": { "tags": [ "Consumer Pricing" ], "summary": "List Prices", "description": "Return prices for valid provider, service package, and pricing arrangement (cash or negotiated) combinations.", "operationId": "v3_query_prices", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesQueryRequest" }, "examples": { "by_provider_negotiated": { "summary": "A provider's negotiated prices", "value": { "package_id": "OB002", "provider_id": "5756", "pricing": { "type": "negotiated", "network_id": "-3776001016975145508" } } }, "by_provider_cash": { "summary": "A provider's cash (self-pay) price", "value": { "package_id": "RA008", "provider_id": "5756", "pricing": { "type": "cash" } } }, "near_point": { "summary": "Near a lat/lng, sorted by distance", "value": { "package_id": "RA008", "pricing": { "type": "cash" }, "location": { "near": { "lat": 39.745961, "lng": -104.971559, "radius_m": 25000 } }, "sort": "distance" } }, "by_zip": { "summary": "Around a ZIP code", "value": { "package_id": "RA008", "pricing": { "type": "cash" }, "location": { "zip": "80218" } } }, "within_zip_codes": { "summary": "Within a set of ZIP codes", "value": { "package_id": "OB002", "pricing": { "type": "negotiated", "network_id": "-3776001016975145508" }, "location": { "within": { "zip_codes": [ "80218", "80210" ] } } } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEnvelope_ProviderPackagePrice_" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/prices/compare": { "post": { "tags": [ "Consumer Pricing" ], "summary": "Get Price Statistics", "description": "Return summary statistics (min, max, average, median, quartiles) over prices matching the same filters as /query, excluding sorting and pagination. Use this endpoint to compare prices across relevant criteria.", "operationId": "v3_compare_prices", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricesCompareRequest" }, "examples": { "by_provider_negotiated": { "summary": "Stats for a provider's negotiated prices", "value": { "package_id": "OB002", "provider_id": "5756", "pricing": { "type": "negotiated", "network_id": "-3776001016975145508" } } }, "cash_within_zip_codes": { "summary": "Cash-price stats within a set of ZIP codes", "value": { "package_id": "RA008", "pricing": { "type": "cash" }, "location": { "within": { "zip_codes": [ "80218", "80210" ] } } } }, "cash_near_point": { "summary": "Cash-price stats near a lat/lng", "value": { "package_id": "RA008", "pricing": { "type": "cash" }, "location": { "near": { "lat": 39.745961, "lng": -104.971559, "radius_m": 25000 } } } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceComparison" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/prices/{price_id}": { "get": { "tags": [ "Consumer Pricing" ], "summary": "Get a Price", "description": "Fetch a single price by its unique price ID. Expand line items to review the priced package composition.", "operationId": "v3_get_price", "parameters": [ { "name": "price_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Price identifier.", "examples": [ "prc_5756.OB002.-3776001016975145508" ], "title": "Price Id" }, "description": "Price identifier." }, { "name": "expand", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PriceExpand" } }, { "type": "null" } ], "description": "Relations to inline. Repeat the param to request several.", "examples": [ [ "line_items" ] ], "title": "Expand" }, "description": "Relations to inline. Repeat the param to request several." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderPackagePrice" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v3/personalized-estimates": { "post": { "tags": [ "Consumer Pricing" ], "operationId": "v3_list_personalized_estimates", "summary": "List personalized prices", "description": "Get personalized cost estimates for this member. If we haven't checked their eligibility yet, you'll get a 202 back. Just retry in a bit. The member must have given consent (`consent_attested` must be true).", "parameters": [ { "name": "expand", "in": "query", "required": false, "description": "Optional items to expand on", "schema": { "type": "array", "items": { "type": "string", "enum": [ "line_items" ] } }, "style": "form", "explode": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimatesQueryRequest" }, "example": { "package_id": "GA003", "provider_id": "5756", "pricing": { "type": "negotiated", "network_id": "-3776001016975145508" }, "member_eligibility": { "first_name": "test123", "last_name": "test123", "date_of_birth": "2001-01-01", "member_id": "test123", "consent_attested": true }, "location": null, "sort": null, "sort_direction": "asc", "page_size": 25, "cursor": null } } } }, "responses": { "200": { "description": "Personalized estimates ready.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ConsumerSiteListEnvelopePersonalizedEstimate" }, { "type": "object", "properties": { "benefits_summary": { "$ref": "#/components/schemas/ConsumerSiteBenefitsSummary" } }, "required": [ "benefits_summary" ] } ] }, "example": { "object": "list", "items": [ { "object": "personalized_estimate", "provider": { "id": "prov_01hxyz", "name": "Example Medical Center" }, "package": { "id": "pkg_01hxyz", "name": "Knee replacement - partial" }, "pricing": { "type": "negotiated", "network": { "id": "482910", "name": "Example PPO Network" }, "payer": { "id": "payer_01hxyz", "name": "Example Payer" } }, "total_allowed_amount": { "amount": "620.00", "minor_units": 62000, "currency": "USD" }, "member_cost_share": { "total": { "amount": "185.00", "minor_units": 18500, "currency": "USD" }, "amount_towards_deductible": { "amount": "50.00", "minor_units": 5000, "currency": "USD" }, "amount_towards_copayment": { "amount": "25.00", "minor_units": 2500, "currency": "USD" }, "amount_towards_coinsurance": { "amount": "110.00", "minor_units": 11000, "currency": "USD" }, "is_deductible_met": false, "is_out_of_pocket_max_met": false }, "sub_package_id": "pkg_01hxyz-A", "line_items": [ { "code": "27442", "code_type": "HCPCS", "fee_type": "base_code", "description": "Knee Joint Resurfacing or Reconstruction", "association_rate": 0.91 }, { "code": "27442", "code_type": "HCPCS", "fee_type": "professional_fee", "description": "Knee Joint Resurfacing or Reconstruction", "association_rate": 0.91 }, { "code": "C1776", "code_type": "HCPCS", "fee_type": "facility_fee", "description": "Implantable Joint Device for Motion Restoration", "association_rate": 0.85 }, { "code": "0370", "code_type": "RC", "fee_type": "facility_fee", "description": "Anesthesia - General", "association_rate": 0.94 }, { "code": "97116", "code_type": "HCPCS", "fee_type": "optional_fee", "description": "Therapeutic gait training of 1+ areas for 15 min each", "association_rate": 0.35 } ] } ], "page": { "size": 1, "total": 1, "next_cursor": null }, "no_data_reason": null, "benefits_summary": { "remaining_deductible": 500.0, "total_deductible": 1500.0, "remaining_out_of_pocket_max": 2000.0, "total_out_of_pocket_max": 6000.0, "benefit_categories": [ { "category": "office_visit", "coinsurance": 0.2, "copayment": 0.0, "deductible": null } ], "limitations": [], "deductible_accumulator_type": "individual", "out_of_pocket_accumulator_type": "individual" } } } } }, "202": { "description": "Eligibility check in progress \u2014 retry after a short delay.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "processing" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } } } }, "400": { "description": "The request body is malformed or fails validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "invalid_request", "message": "Request body failed validation.", "hint": "Field required", "expected": null, "received": null, "field": "member_id" } } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "403": { "description": "The token does not grant access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "forbidden", "message": "Forbidden.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "404": { "description": "The requested plan or network is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "plan_not_found", "message": "Plan/network not supported.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "422": { "description": "Member eligibility or search criteria could not be resolved. Inspect `error.code` and `error.hint` for the specific problem and suggested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "member_not_found", "message": "No member found matching the details provided. Retry with different member information.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "429": { "description": "The request was rate limited. Retry after a delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "hint": "Retry after a short delay.", "expected": null, "received": null, "field": null } } } } }, "500": { "description": "An eligibility service or unexpected internal error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "An unexpected error occurred.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "502": { "description": "The upstream authorization service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "authorization_unavailable", "message": "Authorization service unavailable.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "503": { "description": "The payer or pricing service is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "pricing_unavailable", "message": "The pricing service is temporarily unavailable. Please retry later.", "hint": null, "expected": null, "received": null, "field": null } } } } } } }, "servers": [ { "url": "https://eligibility.turquoiseconnect.health" } ] }, "/v3/personalized-estimates/compare": { "post": { "tags": [ "Consumer Pricing" ], "operationId": "v3_compare_personalized_estimates", "summary": "Compare personalized prices across providers for a package", "description": "Compare what this member would pay out-of-pocket across providers for the givenpackage. You'll get back the min, max, average, median, and quartiles. If we haven't checked their eligibility yet, you'll get a 202 back, just retry in a bit. The member must have given consent (`consent_attested` must be true).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePriceComparisonInput" }, "example": { "package_id": "GA003", "provider_id": null, "pricing": { "type": "negotiated", "network_id": "-3776001016975145508" }, "member_eligibility": { "first_name": "test123", "last_name": "test123", "date_of_birth": "2001-01-01", "member_id": "test123", "consent_attested": true }, "location": { "zip": "80218" } } } } }, "responses": { "200": { "description": "Price comparison statistics for the requested package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePriceComparison" }, "example": { "object": "price_comparison", "count": 8, "stats": { "min": { "amount": "120.00", "minor_units": 12000, "currency": "USD" }, "max": { "amount": "540.00", "minor_units": 54000, "currency": "USD" }, "avg": { "amount": "310.25", "minor_units": 31025, "currency": "USD" }, "median": { "amount": "295.00", "minor_units": 29500, "currency": "USD" }, "q1": { "amount": "200.00", "minor_units": 20000, "currency": "USD" }, "q3": { "amount": "410.00", "minor_units": 41000, "currency": "USD" } } } } } }, "202": { "description": "Eligibility check in progress \u2014 retry after a short delay.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "processing" }, "message": { "type": "string" } }, "required": [ "status", "message" ] } } } }, "400": { "description": "The request body is malformed or fails validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "invalid_request", "message": "Request body failed validation.", "hint": "Field required", "expected": null, "received": null, "field": "member_id" } } } } }, "401": { "description": "The bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "Unauthorized.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "403": { "description": "The token does not grant access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "forbidden", "message": "Forbidden.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "404": { "description": "The requested plan or network is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "plan_not_found", "message": "Plan/network not supported.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "422": { "description": "Member eligibility or search criteria could not be resolved. Inspect `error.code` and `error.hint` for the specific problem and suggested action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "member_not_found", "message": "No member found matching the details provided. Retry with different member information.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "429": { "description": "The request was rate limited. Retry after a delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "hint": "Retry after a short delay.", "expected": null, "received": null, "field": null } } } } }, "500": { "description": "An eligibility service or unexpected internal error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "An unexpected error occurred.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "502": { "description": "The upstream authorization service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "authorization_unavailable", "message": "Authorization service unavailable.", "hint": null, "expected": null, "received": null, "field": null } } } } }, "503": { "description": "The payer or pricing service is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorResponse" }, "example": { "error": { "code": "pricing_unavailable", "message": "The pricing service is temporarily unavailable. Please retry later.", "hint": null, "expected": null, "received": null, "field": null } } } } } } }, "servers": [ { "url": "https://eligibility.turquoiseconnect.health" } ] } }, "components": { "schemas": { "BillingCode": { "properties": { "code": { "type": "string", "title": "Code", "description": "Billing code.", "examples": [ "59510" ] }, "code_type": { "type": "string", "title": "Code Type", "description": "Billing code type.", "examples": [ "HCPCS" ] } }, "type": "object", "required": [ "code", "code_type" ], "title": "BillingCode", "description": "A billing code and its coding system. Shared vocabulary primitive \u2014\nused wherever a resource surfaces a structured code (e.g.\nPackage.anchor_codes); semantics belong to the field that carries it." }, "ComparisonStats": { "properties": { "min": { "$ref": "#/components/schemas/Money" }, "max": { "$ref": "#/components/schemas/Money" }, "avg": { "$ref": "#/components/schemas/Money" }, "median": { "$ref": "#/components/schemas/Money" }, "q1": { "$ref": "#/components/schemas/Money" }, "q3": { "$ref": "#/components/schemas/Money" } }, "type": "object", "required": [ "min", "max", "avg", "median", "q1", "q3" ], "title": "ComparisonStats" }, "EntityRef": { "properties": { "id": { "type": "string", "title": "Id", "description": "Entity identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Re-resolve via search rather than persisting long-term." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Display name; null when reference data is missing." } }, "type": "object", "required": [ "id" ], "title": "EntityRef", "description": "Two-field reference stub. `expand=` swaps it for the full entity.\n\n`name` is nullable by design: 0.8% of priced providers have no reference\nrow (measured 07/2026), and the v3 rule is to emit the stub with a null\nname rather than silently dropping the priced row." }, "ErrorCode": { "type": "string", "enum": [ "invalid_request", "invalid_id_format", "insufficient_scope", "location_ambiguous", "unresolvable_location", "not_found", "invalid_expand", "permission_denied", "rate_limited", "search_unavailable", "conflicting_parameters" ], "title": "ErrorCode", "description": "Stable error code registry for the v3 surface. Switch on this in code." }, "ErrorPayload": { "properties": { "code": { "$ref": "#/components/schemas/ErrorCode", "description": "Stable, documented error code." }, "message": { "type": "string", "title": "Message", "description": "Human-readable error summary." }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hint", "description": "Actionable suggestion for the caller, when applicable." }, "expected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected", "description": "What the API expected." }, "received": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Received", "description": "What the API actually received." }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Field", "description": "Dot-path of the offending request field." } }, "type": "object", "required": [ "code", "message" ], "title": "ErrorPayload" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorPayload" } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse" }, "LineItem": { "properties": { "code": { "type": "string", "title": "Code", "description": "Billing code." }, "code_type": { "type": "string", "title": "Code Type", "description": "Billing code type." }, "fee_type": { "type": "string", "title": "Fee Type", "description": "Fee category: base_code, facility_fee, professional_fee, optional_fee." }, "description": { "type": "string", "title": "Description", "description": "Human-readable line item description." }, "association_rate": { "type": "number", "title": "Association Rate", "description": "Likelihood this line item is part of the package (0-1)." } }, "type": "object", "required": [ "code", "code_type", "fee_type", "description", "association_rate" ], "title": "LineItem", "description": "A component of a package's composition (from `api_ssp_contents`).", "examples": [ { "association_rate": 0.4491, "code": "786", "code_type": "MS-DRG", "description": "CESAREAN SECTION WITHOUT STERILIZATION WITH MCC", "fee_type": "base_code" } ] }, "ListEnvelope_LineItem_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "items": { "items": { "$ref": "#/components/schemas/LineItem" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/NoDataReason" }, { "type": "null" } ], "description": "Set when `items` is empty. `no_data` means no matching records exist; `permission_denied` means matching records exist but are excluded by your data permissions." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures", "description": "Human-readable caveats about what this result does and does not imply." } }, "type": "object", "required": [ "items", "page" ], "title": "ListEnvelope[LineItem]" }, "ListEnvelope_Network_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "items": { "items": { "$ref": "#/components/schemas/Network" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/NoDataReason" }, { "type": "null" } ], "description": "Set when `items` is empty. `no_data` means no matching records exist; `permission_denied` means matching records exist but are excluded by your data permissions." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures", "description": "Human-readable caveats about what this result does and does not imply." } }, "type": "object", "required": [ "items", "page" ], "title": "ListEnvelope[Network]" }, "ListEnvelope_Package_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "items": { "items": { "$ref": "#/components/schemas/Package" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/NoDataReason" }, { "type": "null" } ], "description": "Set when `items` is empty. `no_data` means no matching records exist; `permission_denied` means matching records exist but are excluded by your data permissions." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures", "description": "Human-readable caveats about what this result does and does not imply." } }, "type": "object", "required": [ "items", "page" ], "title": "ListEnvelope[Package]" }, "ListEnvelope_Payer_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "items": { "items": { "$ref": "#/components/schemas/Payer" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/NoDataReason" }, { "type": "null" } ], "description": "Set when `items` is empty. `no_data` means no matching records exist; `permission_denied` means matching records exist but are excluded by your data permissions." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures", "description": "Human-readable caveats about what this result does and does not imply." } }, "type": "object", "required": [ "items", "page" ], "title": "ListEnvelope[Payer]" }, "ListEnvelope_ProviderPackagePrice_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "items": { "items": { "$ref": "#/components/schemas/ProviderPackagePrice" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/NoDataReason" }, { "type": "null" } ], "description": "Set when `items` is empty. `no_data` means no matching records exist; `permission_denied` means matching records exist but are excluded by your data permissions." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures", "description": "Human-readable caveats about what this result does and does not imply." } }, "type": "object", "required": [ "items", "page" ], "title": "ListEnvelope[ProviderPackagePrice]" }, "ListEnvelope_Provider_": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "default": "list" }, "items": { "items": { "$ref": "#/components/schemas/Provider" }, "type": "array", "title": "Items" }, "page": { "$ref": "#/components/schemas/PageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/NoDataReason" }, { "type": "null" } ], "description": "Set when `items` is empty. `no_data` means no matching records exist; `permission_denied` means matching records exist but are excluded by your data permissions." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures", "description": "Human-readable caveats about what this result does and does not imply." } }, "type": "object", "required": [ "items", "page" ], "title": "ListEnvelope[Provider]" }, "Location": { "properties": { "near": { "anyOf": [ { "$ref": "#/components/schemas/LocationNear" }, { "type": "null" } ] }, "within": { "anyOf": [ { "$ref": "#/components/schemas/LocationWithin" }, { "type": "null" } ] }, "zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zip", "description": "Resolves the ZIP to its centroid, then runs `near`.", "examples": [ "80218" ] } }, "type": "object", "title": "Location", "description": "Structured location intent: exactly one of the three modes." }, "LocationNear": { "properties": { "lat": { "type": "number", "title": "Lat", "description": "Latitude of the search anchor.", "examples": [ 39.745961 ] }, "lng": { "type": "number", "title": "Lng", "description": "Longitude of the search anchor.", "examples": [ -104.971559 ] }, "radius_m": { "type": "integer", "minimum": 1.0, "title": "Radius M", "description": "Search radius in meters.", "default": 25000, "examples": [ 25000 ] } }, "type": "object", "required": [ "lat", "lng" ], "title": "LocationNear" }, "LocationWithin": { "properties": { "state": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2 }, { "type": "null" } ], "title": "State", "description": "Two-letter USPS state code.", "examples": [ "CO" ] }, "cbsa": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cbsa", "description": "CBSA name (case-insensitive substring match).", "examples": [ "Denver-Aurora-Centennial, CO" ] }, "zip_codes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Zip Codes", "description": "ZIP codes (exact match, any-of).", "examples": [ [ "80218", "80210" ] ] } }, "type": "object", "title": "LocationWithin", "description": "Region filter. Exactly one of state / cbsa / zip_codes." }, "MatchContext": { "properties": { "score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Score", "description": "Semantic similarity (0-1)." }, "distance_m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Distance M", "description": "Distance from the search anchor in meters." } }, "type": "object", "title": "MatchContext", "description": "Query-relative metadata for resources with a concrete location." }, "Money": { "properties": { "amount": { "type": "string", "title": "Amount", "description": "String-decimal value, e.g. \"1250.00\"." }, "minor_units": { "type": "integer", "title": "Minor Units", "description": "Integer minor units, e.g. 125000." }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code. Always USD today.", "default": "USD" } }, "type": "object", "required": [ "amount", "minor_units" ], "title": "Money", "description": "The single money shape used everywhere a monetary value appears." }, "Network": { "properties": { "object": { "type": "string", "const": "network", "title": "Object", "default": "network" }, "id": { "type": "string", "title": "Id", "description": "Network identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Re-resolve via search rather than persisting long-term." }, "name": { "type": "string", "title": "Name", "description": "Display name of the network." }, "payer": { "$ref": "#/components/schemas/EntityRef", "description": "The network's payer as an {id, name} stub; the full entity lives at /v3/payers/{id}." }, "context": { "anyOf": [ { "$ref": "#/components/schemas/SearchContext" }, { "type": "null" } ], "description": "Query-relative metadata (search only)." } }, "type": "object", "required": [ "id", "name", "payer" ], "title": "Network", "examples": [ { "id": "-3776001016975145508", "name": "National OAP", "object": "network", "payer": { "id": "76", "name": "Cigna" } } ] }, "NoDataReason": { "type": "string", "enum": [ "no_data", "permission_denied" ], "title": "NoDataReason" }, "Package": { "properties": { "object": { "type": "string", "const": "package", "title": "Object", "default": "package" }, "id": { "type": "string", "title": "Id", "description": "Package identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Re-resolve via search rather than persisting long-term." }, "type": { "type": "string", "const": "ssp", "title": "Type", "description": "Package taxonomy. Only Standard Service Packages ('ssp') are served today; other package types (e.g. consumer bundles) may be added as they become servable.", "default": "ssp" }, "name": { "type": "string", "title": "Name", "description": "Display name of the service package." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Patient-facing description of the package." }, "anchor_codes": { "items": { "$ref": "#/components/schemas/BillingCode" }, "type": "array", "title": "Anchor Codes", "description": "The package's comprehensive anchor (base) billing codes \u2014 the rows billed as the anchor itself, not its professional-fee counterparts. Every package is expected to carry at least one. In the current catalog every anchor code maps to exactly one package (measured 07/2026), so ?anchor_code= behaves as a unique lookup \u2014 but that is an observed property, not a guarantee: the lookup returns every package anchored by the code." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/SearchContext" }, { "type": "null" } ], "description": "Query-relative metadata (search only)." } }, "type": "object", "required": [ "id", "name" ], "title": "Package", "examples": [ { "anchor_codes": [ { "code": "59510", "code_type": "HCPCS" }, { "code": "784", "code_type": "MS-DRG" }, { "code": "785", "code_type": "MS-DRG" }, { "code": "786", "code_type": "MS-DRG" } ], "description": "Cesarean delivery (C-section) is a surgical procedure in which the baby is delivered through incisions made in the abdomen and uterus. It may be planned in advance due to specific medical conditions or performed as an emergency if complications arise during labor. The procedure is done under regional or general anesthesia, and most patients stay in the hospital for two to four days. Recovery from a C-section typically takes longer than from a vaginal delivery, and your care team will provide instructions for wound care and activity during healing.", "disclosures": [ "The full package depends on your provider and insurance plan. A final price includes additional institutional and professional fee codes." ], "id": "OB002", "name": "Delivery - caesarean", "object": "package", "type": "ssp" } ] }, "PageMeta": { "properties": { "size": { "type": "integer", "title": "Size", "description": "Number of items in this page." }, "total": { "type": "integer", "title": "Total", "description": "Count of the full filtered set, not just this page." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page; null when exhausted." } }, "type": "object", "required": [ "size", "total" ], "title": "PageMeta" }, "Payer": { "properties": { "object": { "type": "string", "const": "payer", "title": "Object", "default": "payer" }, "id": { "type": "string", "title": "Id", "description": "Payer identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Re-resolve via search rather than persisting long-term." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Display name; null when reference data is missing." }, "context": { "anyOf": [ { "$ref": "#/components/schemas/SearchContext" }, { "type": "null" } ], "description": "Query-relative metadata (search only)." } }, "type": "object", "required": [ "id" ], "title": "Payer", "examples": [ { "id": "76", "name": "Cigna", "object": "payer" } ] }, "PriceComparison": { "properties": { "object": { "type": "string", "const": "price_comparison", "title": "Object", "default": "price_comparison" }, "count": { "type": "integer", "title": "Count", "description": "Number of prices the statistics were computed over." }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/ComparisonStats" }, { "type": "null" } ], "description": "Null when count is 0." }, "disclosures": { "items": { "type": "string" }, "type": "array", "title": "Disclosures" }, "meta": { "$ref": "#/components/schemas/ResponseMeta" } }, "type": "object", "required": [ "count" ], "title": "PriceComparison" }, "PriceExpand": { "type": "string", "enum": [ "line_items" ], "title": "PriceExpand", "description": "Optional relations the price detail endpoint can inline via `expand`." }, "PriceSort": { "type": "string", "enum": [ "total", "distance" ], "title": "PriceSort", "description": "Sort options for price listings. `distance` requires a near/zip location." }, "PricesCompareRequest": { "properties": { "package_id": { "type": "string", "minLength": 1, "title": "Package Id", "examples": [ "OB002" ] }, "provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Id", "examples": [ "5756" ] }, "pricing": { "oneOf": [ { "$ref": "#/components/schemas/PricingCash" }, { "$ref": "#/components/schemas/PricingNegotiated" } ], "title": "Pricing", "discriminator": { "propertyName": "type", "mapping": { "cash": "#/components/schemas/PricingCash", "negotiated": "#/components/schemas/PricingNegotiated" } } }, "location": { "anyOf": [ { "$ref": "#/components/schemas/Location" }, { "type": "null" } ] } }, "type": "object", "required": [ "package_id", "pricing" ], "title": "PricesCompareRequest", "description": "POST /v3/prices/compare body \u2014 the query shape minus sort/expand/pagination." }, "PricesQueryRequest": { "properties": { "package_id": { "type": "string", "minLength": 1, "title": "Package Id", "examples": [ "OB002" ] }, "provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Id", "examples": [ "5756" ] }, "pricing": { "oneOf": [ { "$ref": "#/components/schemas/PricingCash" }, { "$ref": "#/components/schemas/PricingNegotiated" } ], "title": "Pricing", "discriminator": { "propertyName": "type", "mapping": { "cash": "#/components/schemas/PricingCash", "negotiated": "#/components/schemas/PricingNegotiated" } } }, "location": { "anyOf": [ { "$ref": "#/components/schemas/Location" }, { "type": "null" } ] }, "sort": { "$ref": "#/components/schemas/PriceSort", "description": "`total` (default) or `distance` (requires a near/zip location).", "default": "total" }, "sort_direction": { "type": "string", "enum": [ "asc", "desc" ], "title": "Sort Direction", "description": "Sort order. Defaults to ascending (lowest total / nearest first).", "default": "asc" }, "page_size": { "type": "integer", "maximum": 250.0, "minimum": 1.0, "title": "Page Size", "default": 25 }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } }, "type": "object", "required": [ "package_id", "pricing" ], "title": "PricesQueryRequest" }, "PricingCash": { "properties": { "type": { "type": "string", "const": "cash", "title": "Type" } }, "type": "object", "required": [ "type" ], "title": "PricingCash" }, "PricingNegotiated": { "properties": { "type": { "type": "string", "const": "negotiated", "title": "Type" }, "network_id": { "type": "string", "title": "Network Id", "description": "Network identifier (string-wrapped 64-bit integer).", "examples": [ "-3776001016975145508" ] } }, "type": "object", "required": [ "type", "network_id" ], "title": "PricingNegotiated" }, "PricingResolved": { "properties": { "type": { "type": "string", "enum": [ "cash", "negotiated" ], "title": "Type" }, "network": { "anyOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "type": "null" } ] }, "payer": { "anyOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "type": "null" } ] } }, "type": "object", "required": [ "type" ], "title": "PricingResolved", "description": "The resolved payment arrangement on a price. Cash prices omit\nnetwork/payer; negotiated prices carry both as reference stubs." }, "Provider": { "properties": { "object": { "type": "string", "const": "provider", "title": "Object", "default": "provider" }, "id": { "type": "string", "title": "Id", "description": "Provider identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Re-resolve via search rather than persisting long-term." }, "name": { "type": "string", "title": "Name", "description": "Provider facility or organization name." }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "Provider type as reported in the dataset." }, "npi": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Npi", "description": "National Provider Identifier." }, "address": { "$ref": "#/components/schemas/ProviderAddress" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/MatchContext" }, { "type": "null" } ], "description": "Query-relative metadata (near/zip mode only)." } }, "type": "object", "required": [ "id", "name", "address" ], "title": "Provider", "examples": [ { "address": { "city": "Denver", "latitude": 39.745961, "longitude": -104.971559, "state": "CO", "zip_code": "80218" }, "context": { "distance_m": 1644.0 }, "id": "5756", "name": "Intermountain Health Saint Joseph Hospital", "npi": "1417946021", "object": "provider", "type": "Short Term Acute Care Hospital" } ] }, "ProviderAddress": { "properties": { "city": { "type": "string", "title": "City", "description": "City the provider is located in." }, "state": { "type": "string", "title": "State", "description": "Two-letter USPS state code." }, "zip_code": { "type": "string", "title": "Zip Code", "description": "Provider ZIP code." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Latitude", "description": "Provider HQ latitude; null for ~6% of providers." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Longitude", "description": "Provider HQ longitude; null for ~6% of providers." } }, "type": "object", "required": [ "city", "state", "zip_code" ], "title": "ProviderAddress" }, "ProviderPackagePrice": { "properties": { "object": { "type": "string", "const": "price", "title": "Object", "default": "price" }, "id": { "type": "string", "title": "Id", "description": "Price identifier (encodes the provider \u00d7 package \u00d7 pricing grain). Upstream-derived from the dataset and may change as the dataset is rebuilt. Re-resolve via search rather than persisting long-term." }, "provider": { "$ref": "#/components/schemas/Provider", "description": "Full provider entity (always inlined)." }, "package": { "$ref": "#/components/schemas/EntityRef", "description": "Reference stub." }, "pricing": { "$ref": "#/components/schemas/PricingResolved" }, "total": { "$ref": "#/components/schemas/Money", "description": "The package-total price at this grain." }, "line_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/LineItem" }, "type": "array" }, { "type": "null" } ], "title": "Line Items", "description": "Package composition; present when expand=line_items (detail only)." }, "context": { "anyOf": [ { "$ref": "#/components/schemas/MatchContext" }, { "type": "null" } ] } }, "type": "object", "required": [ "id", "provider", "package", "pricing", "total" ], "title": "ProviderPackagePrice", "examples": [ { "id": "prc_5756.OB002.-3776001016975145508", "object": "price", "package": { "id": "OB002", "name": "Delivery - caesarean" }, "pricing": { "network": { "id": "-3776001016975145508", "name": "National OAP" }, "payer": { "id": "76", "name": "Cigna" }, "type": "negotiated" }, "provider": { "address": { "city": "Denver", "latitude": 39.745961, "longitude": -104.971559, "state": "CO", "zip_code": "80218" }, "id": "5756", "name": "Intermountain Health Saint Joseph Hospital", "npi": "1417946021", "object": "provider", "type": "Short Term Acute Care Hospital" }, "total": { "amount": "34705.48", "currency": "USD", "minor_units": 3470548 } } ] }, "ResponseMeta": { "properties": { "dataset_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dataset Version", "description": "Version marker of the underlying dataset; null until the loader exposes one." } }, "type": "object", "title": "ResponseMeta" }, "SearchContext": { "properties": { "score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Score", "description": "Semantic similarity (0-1)." } }, "type": "object", "title": "SearchContext", "description": "Query-relative semantic-search metadata." }, "ConsumerPricingV2ErrorCode": { "enum": [ "INVALID_REQUEST", "INVALID_STATE_FORMAT", "INVALID_ID_FORMAT", "INVALID_EXPAND", "INSUFFICIENT_SCOPE", "LOCATION_REQUIRED", "LOCATION_AMBIGUOUS", "UNRESOLVABLE_LOCATION", "NOT_FOUND", "INSUFFICIENT_DATA", "RATE_LIMITED", "PERMISSION_DENIED", "SEARCH_UNAVAILABLE" ], "type": "string", "title": "ConsumerPricingV2ErrorCode", "description": "Stable error code registry for Consumer Pricing v2. Switch on this in code." }, "ConsumerSiteBenefitCategory": { "properties": { "category": { "title": "Category", "type": "string" }, "coinsurance": { "title": "Coinsurance", "type": "number" }, "copayment": { "title": "Copayment", "type": "number" }, "deductible": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "`0` means deductible does not apply. `null` means plan deductible applies", "title": "Deductible" } }, "required": [ "category", "coinsurance", "copayment", "deductible" ], "title": "BenefitCategory", "type": "object" }, "ConsumerSiteBenefitsSummary": { "properties": { "remaining_deductible": { "description": "Remaining deductible depends on accumulator type:\n\n- **Embedded**: Both individual and family deductibles exist. Met when either is exceeded; uses whichever remaining amount (individual or family) is smaller.\n- **Aggregate**: Only a family deductible exists. Met only when the family accumulator is exceeded; uses remaining family deductible.\n- **Individual**: No family accumulator exists. Met once individual accumulator is reached; uses the remaining individual deductible.\n- **Zero**: The deductible is $0. Coverage kicks in immediately.\n\n`remaining_deductible` and `total_deductible` use the same accumulator value (individual or family)", "title": "Remaining Deductible", "type": "number" }, "total_deductible": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total deductible depends on accumulator type:\n\n- **Embedded**: Both individual and family deductibles exist. Met when either is exceeded.\n- **Aggregate**: Only a family deductible exists. Met only when the family accumulator is exceeded.\n- **Individual**: No family accumulator exists. Met once individual accumulator is reached.\n- **Zero**: The deductible is $0. Coverage kicks in immediately.\n\n`total_deductible` and `remaining_deductible` use the same accumulator value (individual or family)", "title": "Total Deductible" }, "remaining_out_of_pocket_max": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Remaining out-of-pocket max depends on accumulator type:\n\n- **Embedded**: Both individual and family out-of-pocket maxes exist. Met when either is exceeded, using whichever remaining amount is lower.\n- **Aggregate**: Only a family out-of-pocket max exists. Met when the family accumulator is exceeded.\n- **Individual**: No family accumulator exists. Met once individual accumulator is reached.\n- **Zero**: The out-of-pocket max is $0.\n\n`remaining_out_of_pocket_max` and `total_out_of_pocket_max` use the same accumulator value (individual or family)", "title": "Remaining Out Of Pocket Max" }, "total_out_of_pocket_max": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total out-of-pocket max depends on accumulator type:\n\n- **Embedded**: Both individual and family out-of-pocket maxes exist. Met when either is exceeded, using whichever remaining amount is lower.\n- **Aggregate**: Only a family out-of-pocket max exists. Met when the family accumulator is exceeded.\n- **Individual**: No family accumulator exists. Met once individual accumulator is reached.\n- **Zero**: The out-of-pocket max is $0.\n\n`total_out_of_pocket_max` and `remaining_out_of_pocket_max` use the same accumulator value (individual or family)", "title": "Total Out Of Pocket Max" }, "benefit_categories": { "items": { "$ref": "#/components/schemas/ConsumerSiteBenefitCategory" }, "title": "Benefit Categories", "type": "array" }, "limitations": { "items": { "type": "string" }, "title": "Limitations", "type": "array" }, "deductible_accumulator_type": { "title": "Deductible Accumulator Type", "type": "string" }, "out_of_pocket_accumulator_type": { "title": "Out Of Pocket Accumulator Type", "type": "string" } }, "required": [ "remaining_deductible", "total_deductible", "remaining_out_of_pocket_max", "total_out_of_pocket_max", "benefit_categories", "limitations", "deductible_accumulator_type", "out_of_pocket_accumulator_type" ], "title": "BenefitsSummary", "type": "object" }, "ConsumerSiteComparisonStats": { "description": "ComparisonStats", "properties": { "min": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "max": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "avg": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "median": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "q1": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "q3": { "$ref": "#/components/schemas/ConsumerSiteMoney" } }, "required": [ "min", "max", "avg", "median", "q1", "q3" ], "title": "ComparisonStats", "type": "object" }, "ConsumerSiteEntityRef": { "description": "Two-field reference stub. `expand=` swaps it for the full entity. `name` is nullable by design: 0.8% of priced providers have no reference row (measured 07/2026), and the v3 rule is to emit the stub with a null name rather than silently dropping the priced row.", "properties": { "id": { "description": "Entity identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Re-resolve via search rather than persisting long-term.", "title": "Id", "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" } }, "required": [ "id" ], "title": "EntityRef", "type": "object" }, "ConsumerSiteEnvelopePersonalizedEstimate": { "description": "EnvelopePersonalizedEstimate", "properties": { "items": { "items": { "$ref": "#/components/schemas/ConsumerSiteModulesConsumerPricingV2DtosRatePersonalizedEstimate" }, "title": "Items", "type": "array" }, "page": { "$ref": "#/components/schemas/ConsumerSiteModulesConsumerPricingV2DtosCommonPageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteNoDataReason" }, { "type": "null" } ], "default": null } }, "required": [ "items", "page" ], "title": "EnvelopePersonalizedEstimate", "type": "object" }, "ConsumerSiteLineItem": { "description": "A component of a package's composition (from `api_ssp_contents`).", "properties": { "code": { "description": "Billing code.", "title": "Code", "type": "string" }, "code_type": { "description": "Billing code type.", "title": "Code Type", "type": "string" }, "fee_type": { "description": "Fee category: base_code, facility_fee, professional_fee, optional_fee.", "title": "Fee Type", "type": "string" }, "description": { "description": "Human-readable line item description.", "title": "Description", "type": "string" }, "association_rate": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "description": "Likelihood this line item is part of the package (0-1).", "title": "Association Rate" } }, "required": [ "code", "code_type", "fee_type", "description", "association_rate" ], "title": "LineItem", "type": "object" }, "ConsumerSiteListEnvelopePersonalizedEstimate": { "description": "ListEnvelopePersonalizedEstimate", "properties": { "object": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "list", "title": "Object" }, "items": { "items": { "$ref": "#/components/schemas/ConsumerSiteModulesConsumerPricingV3DtosPersonalizedEstimatePersonalizedEstimate" }, "title": "Items", "type": "array" }, "page": { "$ref": "#/components/schemas/ConsumerSiteModulesConsumerPricingV3DtosCommonPageMeta" }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteNoDataReason" }, { "type": "null" } ], "default": null }, "disclosures": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Human-readable caveats about what this result does and does not imply.", "title": "Disclosures" } }, "required": [ "items", "page" ], "title": "ListEnvelopePersonalizedEstimate", "type": "object" }, "ConsumerSiteListPricesInputV2": { "description": "Inbound payload for the list-prices endpoint.\n\nExtends eligibility fields with optional search parameters forwarded to the\npersonalized-estimates API.", "properties": { "first_name": { "maxLength": 255, "minLength": 1, "title": "First Name", "type": "string" }, "last_name": { "maxLength": 255, "minLength": 1, "title": "Last Name", "type": "string" }, "date_of_birth": { "format": "date", "title": "Date Of Birth", "type": "string" }, "member_id": { "maxLength": 255, "minLength": 1, "title": "Member Id", "type": "string" }, "consent_attested": { "const": true, "title": "Consent Attested" }, "network_id": { "title": "Network Id", "type": "integer" }, "ssp_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Ssp Id" }, "provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Id" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteRateCompareLocation" }, { "type": "null" } ], "default": null }, "page_size": { "default": 25, "maximum": 250, "minimum": 1, "title": "Page Size", "type": "integer" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cursor" } }, "required": [ "first_name", "last_name", "date_of_birth", "member_id", "consent_attested", "network_id" ], "title": "ListPricesInputV2", "type": "object" }, "ConsumerSiteLocation": { "description": "Structured location intent: exactly one of the three modes.", "properties": { "near": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteLocationNear" }, { "type": "null" } ], "default": null }, "within": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteLocationWithin" }, { "type": "null" } ], "default": null }, "zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Zip" } }, "title": "Location", "type": "object" }, "ConsumerSiteLocationNear": { "description": "LocationNear", "properties": { "lat": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "description": "Latitude of the search anchor.", "title": "Lat" }, "lng": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "description": "Longitude of the search anchor.", "title": "Lng" }, "radius_m": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": 25000, "description": "Search radius in meters.", "title": "Radius M" } }, "required": [ "lat", "lng" ], "title": "LocationNear", "type": "object" }, "ConsumerSiteLocationWithin": { "description": "Region filter. Exactly one of state / cbsa / zip_codes.", "properties": { "state": { "anyOf": [ { "maxLength": 2, "minLength": 2, "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "cbsa": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cbsa" }, "zip_codes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Zip Codes" } }, "title": "LocationWithin", "type": "object" }, "ConsumerSiteMemberCostShare": { "description": "MemberCostShare", "properties": { "total": { "allOf": [ { "$ref": "#/components/schemas/ConsumerSiteMoney" } ], "description": "Total out-of-pocket price." }, "amount_towards_deductible": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "amount_towards_copayment": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "amount_towards_coinsurance": { "$ref": "#/components/schemas/ConsumerSiteMoney" }, "is_deductible_met": { "description": "Whether the deductible is fully met at/after this service.", "title": "Is Deductible Met", "type": "boolean" }, "is_out_of_pocket_max_met": { "description": "Whether the OOP maximum is met at/after this service.", "title": "Is Out Of Pocket Max Met", "type": "boolean" } }, "required": [ "total", "amount_towards_deductible", "amount_towards_copayment", "amount_towards_coinsurance", "is_deductible_met", "is_out_of_pocket_max_met" ], "title": "MemberCostShare", "type": "object" }, "ConsumerSiteMemberEligibilityInput": { "description": "Shared eligibility fields carried by all cost-share input payloads.\n\nContains PHI (name/DOB/member id) \u2014 handle per HIPAA controls.", "properties": { "first_name": { "maxLength": 255, "minLength": 1, "title": "First Name", "type": "string" }, "last_name": { "maxLength": 255, "minLength": 1, "title": "Last Name", "type": "string" }, "date_of_birth": { "format": "date", "title": "Date Of Birth", "type": "string" }, "member_id": { "maxLength": 255, "minLength": 1, "title": "Member Id", "type": "string" }, "consent_attested": { "const": true, "title": "Consent Attested" } }, "required": [ "first_name", "last_name", "date_of_birth", "member_id", "consent_attested" ], "title": "MemberEligibilityInput", "type": "object" }, "ConsumerSiteModulesConsumerPricingV2DtosCommonPageMeta": { "description": "Pagination metadata. Cursor is opaque; clients pass it back unchanged.", "properties": { "size": { "description": "Number of items in this page.", "title": "Size", "type": "integer" }, "total": { "description": "Count of the full filtered set, not just this page.", "title": "Total", "type": "integer" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "size", "total" ], "title": "ModulesConsumerPricingV2DtosCommonPageMeta", "type": "object" }, "ConsumerSiteModulesConsumerPricingV2DtosRatePersonalizedEstimate": { "description": "Member out-of-pocket estimate at the (provider \u00d7 ssp \u00d7 [network]) grain. Inherits `Rate`; the inherited `amount`/`amount_cents` carry the member's cost-share total (out-of-pocket), not the full negotiated price. The breakdown fields explain how that total is composed.", "properties": { "price_type": { "description": "`cash` \u21d4 `network_id is null`. `negotiated` otherwise.", "title": "Price Type", "type": "string" }, "provider_id": { "description": "Provider identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Do not bake into URLs, bookmarks, or persistent storage.", "title": "Provider Id", "type": "string" }, "ssp_id": { "description": "SSP identifier. Upstream-derived from the dataset and may change as the dataset is rebuilt. Do not bake into URLs, bookmarks, or persistent storage.", "title": "Ssp Id", "type": "string" }, "network_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Signed 64-bit integer serialized as a string to preserve precision in JSON.", "title": "Network Id" }, "amount": { "description": "String-decimal money value, e.g. \"1250.00\".", "title": "Amount", "type": "string" }, "amount_cents": { "description": "Integer minor units, e.g. 125000.", "title": "Amount Cents", "type": "integer" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "USD", "description": "ISO currency code. Always USD today.", "title": "Currency" }, "amount_towards_deductible": { "description": "Portion of the estimate applied to the deductible.", "title": "Amount Towards Deductible", "type": "string" }, "amount_towards_deductible_cents": { "description": "Integer minor units of `amount_towards_deductible`.", "title": "Amount Towards Deductible Cents", "type": "integer" }, "amount_towards_copayment": { "description": "Portion of the estimate that is a flat copay.", "title": "Amount Towards Copayment", "type": "string" }, "amount_towards_copayment_cents": { "description": "Integer minor units of `amount_towards_copayment`.", "title": "Amount Towards Copayment Cents", "type": "integer" }, "amount_towards_coinsurance": { "description": "Portion of the estimate that is coinsurance.", "title": "Amount Towards Coinsurance", "type": "string" }, "amount_towards_coinsurance_cents": { "description": "Integer minor units of `amount_towards_coinsurance`.", "title": "Amount Towards Coinsurance Cents", "type": "integer" }, "is_deductible_met": { "description": "Whether the member's deductible is fully met by/at this estimate.", "title": "Is Deductible Met", "type": "boolean" }, "is_out_of_pocket_met": { "description": "Whether the member's out-of-pocket max is met by/at this estimate.", "title": "Is Out Of Pocket Met", "type": "boolean" }, "sub_package_code": { "description": "The sub-package the estimate was computed over.", "title": "Sub Package Code", "type": "string" }, "total_negotiated_price": { "description": "Full pre-insurance negotiated price for context.", "title": "Total Negotiated Price", "type": "string" }, "total_negotiated_price_cents": { "description": "Integer minor units of `total_negotiated_price`.", "title": "Total Negotiated Price Cents", "type": "integer" } }, "required": [ "price_type", "provider_id", "ssp_id", "amount", "amount_cents", "amount_towards_deductible", "amount_towards_deductible_cents", "amount_towards_copayment", "amount_towards_copayment_cents", "amount_towards_coinsurance", "amount_towards_coinsurance_cents", "is_deductible_met", "is_out_of_pocket_met", "sub_package_code", "total_negotiated_price", "total_negotiated_price_cents" ], "title": "ModulesConsumerPricingV2DtosRatePersonalizedEstimate", "type": "object" }, "ConsumerSiteModulesConsumerPricingV3DtosCommonPageMeta": { "description": "ModulesConsumerPricingV3DtosCommonPageMeta", "properties": { "size": { "description": "Number of items in this page.", "title": "Size", "type": "integer" }, "total": { "description": "Count of the full filtered set, not just this page.", "title": "Total", "type": "integer" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" } }, "required": [ "size", "total" ], "title": "ModulesConsumerPricingV3DtosCommonPageMeta", "type": "object" }, "ConsumerSiteModulesConsumerPricingV3DtosPersonalizedEstimatePersonalizedEstimate": { "description": "ModulesConsumerPricingV3DtosPersonalizedEstimatePersonalizedEstimate", "properties": { "object": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "personalized_estimate", "title": "Object" }, "provider": { "$ref": "#/components/schemas/ConsumerSiteEntityRef" }, "package": { "$ref": "#/components/schemas/ConsumerSiteEntityRef" }, "pricing": { "$ref": "#/components/schemas/ConsumerSitePricingResolved" }, "total_allowed_amount": { "allOf": [ { "$ref": "#/components/schemas/ConsumerSiteMoney" } ], "description": "Amount that insurance company + patient pay for the service." }, "member_cost_share": { "$ref": "#/components/schemas/ConsumerSiteMemberCostShare" }, "sub_package_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Sub Package Id" }, "line_items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ConsumerSiteLineItem" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Line Items" } }, "required": [ "provider", "package", "pricing", "total_allowed_amount", "member_cost_share" ], "title": "ModulesConsumerPricingV3DtosPersonalizedEstimatePersonalizedEstimate", "type": "object" }, "ConsumerSiteMoney": { "description": "The single money shape used everywhere a monetary value appears.", "properties": { "amount": { "description": "String-decimal value, e.g. \"1250.00\".", "title": "Amount", "type": "string" }, "minor_units": { "description": "Integer minor units, e.g. 125000.", "title": "Minor Units", "type": "integer" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "USD", "description": "ISO currency code. Always USD today.", "title": "Currency" } }, "required": [ "amount", "minor_units" ], "title": "Money", "type": "object" }, "ConsumerSiteNoDataReason": { "description": "NoDataReason", "enum": [ "no_data", "permission_denied" ], "title": "NoDataReason", "type": "string" }, "ConsumerSitePersonalizedEstimateBreakdown": { "description": "Member out-of-pocket breakdown for one (provider x ssp x network) tuple Totals are member's expected out-of-pocket for the winning sub-package. line_items reuse the provider-breakdown representation.", "properties": { "price_type": { "title": "Price Type", "type": "string" }, "provider_id": { "title": "Provider Id", "type": "string" }, "ssp_id": { "title": "Ssp Id", "type": "string" }, "network_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Signed 64-bit integer serialized as a string to preserve precision in JSON.", "title": "Network Id" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "USD", "description": "ISO currency code. Always USD today.", "title": "Currency" }, "amount": { "description": "Member out-of-pocket total for the winning sub-package.", "title": "Amount", "type": "string" }, "amount_cents": { "description": "Integer minor units of `amount`.", "title": "Amount Cents", "type": "integer" }, "amount_towards_deductible": { "description": "Portion of the out-of-pocket applied to the deductible.", "title": "Amount Towards Deductible", "type": "string" }, "amount_towards_deductible_cents": { "description": "Integer minor units of `amount_towards_deductible`.", "title": "Amount Towards Deductible Cents", "type": "integer" }, "amount_towards_copayment": { "description": "Portion of the out-of-pocket that is a flat copay.", "title": "Amount Towards Copayment", "type": "string" }, "amount_towards_copayment_cents": { "description": "Integer minor units of `amount_towards_copayment`.", "title": "Amount Towards Copayment Cents", "type": "integer" }, "amount_towards_coinsurance": { "description": "Portion of the out-of-pocket that is coinsurance.", "title": "Amount Towards Coinsurance", "type": "string" }, "amount_towards_coinsurance_cents": { "description": "Integer minor units of `amount_towards_coinsurance`.", "title": "Amount Towards Coinsurance Cents", "type": "integer" }, "is_deductible_met": { "description": "Whether the member's deductible is fully met by/at this estimate.", "title": "Is Deductible Met", "type": "boolean" }, "is_out_of_pocket_met": { "description": "Whether the member's out-of-pocket max is met by/at this estimate.", "title": "Is Out Of Pocket Met", "type": "boolean" }, "total_negotiated_price": { "description": "Full pre-insurance negotiated price for context.", "title": "Total Negotiated Price", "type": "string" }, "total_negotiated_price_cents": { "description": "Integer minor units of `total_negotiated_price`.", "title": "Total Negotiated Price Cents", "type": "integer" }, "sub_package_code": { "description": "The winning sub-package the breakdown was computed over.", "title": "Sub Package Code", "type": "string" }, "line_items": { "items": { "$ref": "#/components/schemas/ConsumerSiteRateBreakdownLineItem" }, "title": "Line Items", "type": "array" } }, "required": [ "price_type", "provider_id", "ssp_id", "amount", "amount_cents", "amount_towards_deductible", "amount_towards_deductible_cents", "amount_towards_copayment", "amount_towards_copayment_cents", "amount_towards_coinsurance", "amount_towards_coinsurance_cents", "is_deductible_met", "is_out_of_pocket_met", "total_negotiated_price", "total_negotiated_price_cents", "sub_package_code", "line_items" ], "title": "PersonalizedEstimateBreakdown", "type": "object" }, "ConsumerSitePersonalizedEstimateBreakdownEnvelope": { "description": "Named envelope for shorter PersonalizedEstimateBreakdownEnvelope", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateBreakdown" }, { "type": "null" } ], "default": null }, "no_data_reason": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteNoDataReason" }, { "type": "null" } ], "default": null } }, "title": "PersonalizedEstimateBreakdownEnvelope", "type": "object" }, "ConsumerSitePersonalizedEstimateErrorCode": { "description": "Stable error codes returned by the v3 personalized-estimate endpoints.\n\nUppercase codes come from Consumer Pricing v3. Lowercase codes are specific to\npersonalized-estimate eligibility and authorization.", "enum": [ "internal_server_error", "eligibility_service_error", "unsupported_tpa", "unavailable_payer", "invalid_dob", "invalid_member_id", "invalid_member_name", "member_not_found", "no_active_coverage", "plan_not_found", "pricing_unavailable", "invalid_json", "unauthorized", "forbidden", "authorization_unavailable", "invalid_request", "invalid_id_format", "insufficient_scope", "location_ambiguous", "unresolvable_location", "not_found", "invalid_expand", "permission_denied", "rate_limited", "search_unavailable", "conflicting_parameters" ], "title": "PersonalizedEstimateErrorCode", "type": "string" }, "ConsumerSitePersonalizedEstimateErrorCodeV2": { "description": "Stable error codes returned by the v2 personalized-estimate endpoints.\n\nUppercase codes come from Consumer Pricing v2. Lowercase codes are specific to\npersonalized-estimate eligibility and authorization.", "enum": [ "internal_server_error", "eligibility_service_error", "unsupported_tpa", "unavailable_payer", "invalid_dob", "invalid_member_id", "invalid_member_name", "member_not_found", "no_active_coverage", "plan_not_found", "pricing_unavailable", "invalid_json", "unauthorized", "forbidden", "authorization_unavailable", "INVALID_REQUEST", "INVALID_STATE_FORMAT", "INVALID_ID_FORMAT", "INVALID_EXPAND", "INSUFFICIENT_SCOPE", "LOCATION_REQUIRED", "LOCATION_AMBIGUOUS", "UNRESOLVABLE_LOCATION", "NOT_FOUND", "INSUFFICIENT_DATA", "RATE_LIMITED", "PERMISSION_DENIED", "SEARCH_UNAVAILABLE" ], "title": "PersonalizedEstimateErrorCodeV2", "type": "string" }, "ConsumerSitePersonalizedEstimateErrorPayload": { "description": "Details about an error returned by a v3 personalized-estimate endpoint.", "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorCode" } ], "description": "Stable, documented error code. Switch on this in code." }, "message": { "description": "Human-readable error summary, suitable for narration to an end user.", "title": "Message", "type": "string" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Actionable suggestion for the caller, when applicable.", "title": "Hint" }, "expected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What the API expected (format, value range, etc).", "title": "Expected" }, "received": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What the API actually received.", "title": "Received" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Dot-path of the offending request field, when applicable.", "title": "Field" } }, "required": [ "code", "message" ], "title": "PersonalizedEstimateErrorPayload", "type": "object" }, "ConsumerSitePersonalizedEstimateErrorPayloadV2": { "description": "Details about an error returned by a v2 personalized-estimate endpoint.", "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorCodeV2" } ], "description": "Stable, documented error code. Switch on this in code." }, "message": { "description": "Human-readable error summary, suitable for narration to an end user.", "title": "Message", "type": "string" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Actionable suggestion for the caller, when applicable.", "title": "Hint" }, "expected": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What the API expected (format, value range, etc).", "title": "Expected" }, "received": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What the API actually received.", "title": "Received" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Dot-path of the offending request field, when applicable.", "title": "Field" } }, "required": [ "code", "message" ], "title": "PersonalizedEstimateErrorPayloadV2", "type": "object" }, "ConsumerSitePersonalizedEstimateErrorResponse": { "description": "Top-level error envelope for v3 personalized estimates.", "properties": { "error": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorPayload" } }, "required": [ "error" ], "title": "PersonalizedEstimateErrorResponse", "type": "object" }, "ConsumerSitePersonalizedEstimateErrorResponseV2": { "description": "Top-level error envelope for v2 personalized estimates.", "properties": { "error": { "$ref": "#/components/schemas/ConsumerSitePersonalizedEstimateErrorPayloadV2" } }, "required": [ "error" ], "title": "PersonalizedEstimateErrorResponseV2", "type": "object" }, "ConsumerSitePersonalizedEstimatesQueryRequest": { "description": "Inbound payload for the v3 list-prices endpoint.", "properties": { "package_id": { "minLength": 1, "title": "Package Id", "type": "string" }, "provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Id" }, "pricing": { "$ref": "#/components/schemas/ConsumerSitePricingNegotiated" }, "member_eligibility": { "$ref": "#/components/schemas/ConsumerSiteMemberEligibilityInput" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteLocation" }, { "type": "null" } ], "default": null }, "sort": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSitePriceSort" }, { "type": "null" } ], "default": null }, "sort_direction": { "default": "asc", "enum": [ "asc", "desc" ], "title": "Sort Direction", "type": "string" }, "page_size": { "default": 25, "maximum": 250, "minimum": 1, "title": "Page Size", "type": "integer" }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cursor" } }, "required": [ "package_id", "pricing", "member_eligibility" ], "title": "PersonalizedEstimatesQueryRequest", "type": "object" }, "ConsumerSitePriceComparison": { "description": "PriceComparison", "properties": { "object": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "price_comparison", "title": "Object" }, "count": { "description": "Number of prices the statistics were computed over.", "title": "Count", "type": "integer" }, "stats": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteComparisonStats" }, { "type": "null" } ], "default": null }, "disclosures": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Disclosures" }, "meta": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteResponseMeta" }, { "type": "null" } ], "default": null } }, "required": [ "count" ], "title": "PriceComparison", "type": "object" }, "ConsumerSitePriceComparisonInput": { "description": "Inbound payload for the v3 compare endpoint.", "properties": { "package_id": { "minLength": 1, "title": "Package Id", "type": "string" }, "provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Id" }, "pricing": { "$ref": "#/components/schemas/ConsumerSitePricingNegotiated" }, "member_eligibility": { "$ref": "#/components/schemas/ConsumerSiteMemberEligibilityInput" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteLocation" }, { "type": "null" } ], "default": null } }, "required": [ "package_id", "pricing", "member_eligibility" ], "title": "PriceComparisonInput", "type": "object" }, "ConsumerSitePriceComparisonInputV2": { "description": "Inbound payload for the compare endpoint.\n\nExtends eligibility fields with the SSP to compare across providers.", "properties": { "first_name": { "maxLength": 255, "minLength": 1, "title": "First Name", "type": "string" }, "last_name": { "maxLength": 255, "minLength": 1, "title": "Last Name", "type": "string" }, "date_of_birth": { "format": "date", "title": "Date Of Birth", "type": "string" }, "member_id": { "maxLength": 255, "minLength": 1, "title": "Member Id", "type": "string" }, "consent_attested": { "const": true, "title": "Consent Attested" }, "network_id": { "title": "Network Id", "type": "integer" }, "ssp_id": { "minLength": 1, "title": "Ssp Id", "type": "string" }, "provider_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Provider Id" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteRateCompareLocation" }, { "type": "null" } ], "default": null } }, "required": [ "first_name", "last_name", "date_of_birth", "member_id", "consent_attested", "network_id", "ssp_id" ], "title": "PriceComparisonInputV2", "type": "object" }, "ConsumerSitePriceSort": { "description": "Sort options for price listings. `distance` requires a near/zip location.", "enum": [ "total", "distance" ], "title": "PriceSort", "type": "string" }, "ConsumerSitePricingNegotiated": { "description": "PricingNegotiated", "properties": { "type": { "title": "Type", "type": "string" }, "network_id": { "description": "Network identifier (string-wrapped 64-bit integer).", "title": "Network Id", "type": "string" } }, "required": [ "type", "network_id" ], "title": "PricingNegotiated", "type": "object" }, "ConsumerSitePricingResolved": { "description": "The resolved payment arrangement on a price. Cash prices omit network/payer; negotiated prices carry both as reference stubs.", "properties": { "type": { "title": "Type", "type": "string" }, "network": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteEntityRef" }, { "type": "null" } ], "default": null }, "payer": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteEntityRef" }, { "type": "null" } ], "default": null } }, "required": [ "type" ], "title": "PricingResolved", "type": "object" }, "ConsumerSiteProviderBreakdownInputV2": { "description": "Inbound payload for the provider-breakdown endpoint.\n\nExtends eligibility fields with required provider and service identifiers.", "properties": { "first_name": { "maxLength": 255, "minLength": 1, "title": "First Name", "type": "string" }, "last_name": { "maxLength": 255, "minLength": 1, "title": "Last Name", "type": "string" }, "date_of_birth": { "format": "date", "title": "Date Of Birth", "type": "string" }, "member_id": { "maxLength": 255, "minLength": 1, "title": "Member Id", "type": "string" }, "consent_attested": { "const": true, "title": "Consent Attested" }, "network_id": { "title": "Network Id", "type": "integer" }, "provider_id": { "minLength": 1, "title": "Provider Id", "type": "string" }, "ssp_id": { "minLength": 1, "title": "Ssp Id", "type": "string" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/ConsumerSiteRateCompareLocation" }, { "type": "null" } ], "default": null } }, "required": [ "first_name", "last_name", "date_of_birth", "member_id", "consent_attested", "network_id", "provider_id", "ssp_id" ], "title": "ProviderBreakdownInputV2", "type": "object" }, "ConsumerSiteRateBreakdownLineItem": { "description": "RateBreakdownLineItem", "properties": { "line_code": { "description": "CPT or HCPCS code.", "title": "Line Code", "type": "string" }, "code_type": { "description": "Billing code type.", "title": "Code Type", "type": "string" }, "fee_type": { "description": "Fee category (professional, facility, etc).", "title": "Fee Type", "type": "string" }, "description": { "description": "Human-readable line item description.", "title": "Description", "type": "string" }, "line_item_association_rate": { "anyOf": [ { "type": "number" }, { "type": "integer" } ], "description": "Likelihood this line item is part of the SSP.", "title": "Line Item Association Rate" } }, "required": [ "line_code", "code_type", "fee_type", "description", "line_item_association_rate" ], "title": "RateBreakdownLineItem", "type": "object" }, "ConsumerSiteRateCompareLocation": { "description": "Structured location for POST bodies. Exactly zero or one mode permitted. Validated by the service layer (location.py shares LocationQuery for GET query params; this is the body equivalent).", "properties": { "near_lat": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Near Lat" }, "near_lng": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Near Lng" }, "near_radius_m": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Near Radius M" }, "within_state": { "anyOf": [ { "maxLength": 2, "minLength": 2, "type": "string" }, { "type": "null" } ], "default": null, "title": "Within State" }, "within_cbsa_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Within Cbsa Name" }, "within_zip_codes": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Within Zip Codes" }, "zip_anchor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Zip Anchor" } }, "title": "RateCompareLocation", "type": "object" }, "ConsumerSiteRateComparison": { "description": "Bounded statistic bundle. No envelope per the ticket.", "properties": { "count": { "description": "Number of rate rows the statistics were computed over.", "title": "Count", "type": "integer" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "USD", "title": "Currency" }, "min_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Min Amount" }, "min_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Min Amount Cents" }, "max_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Max Amount" }, "max_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max Amount Cents" }, "avg_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Avg Amount" }, "avg_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Avg Amount Cents" }, "median_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Median Amount" }, "median_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Median Amount Cents" }, "q1_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Q1 Amount" }, "q1_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Q1 Amount Cents" }, "q3_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Q3 Amount" }, "q3_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Q3 Amount Cents" } }, "required": [ "count" ], "title": "RateComparison", "type": "object" }, "ConsumerSiteResponseMeta": { "description": "ResponseMeta", "properties": { "dataset_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Dataset Version" } }, "title": "ResponseMeta", "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "PartnerBearerToken": { "type": "http", "scheme": "bearer", "description": "OAuth2 access token issued by Turquoise; validated against turquoise-api's /oauth/authorize on every request." } }, "responses": {}, "parameters": {}, "examples": {}, "requestBodies": {}, "headers": {} }, "tags": [ { "name": "Consumer Pricing" } ], "servers": [ { "url": "https://api.turquoise.health" } ] }