{"openapi":"3.1.0","info":{"title":"Arlo Health Pricing API","version":"1.0.0","summary":"US in-network cost estimates and provider network status from insurers' published rate files. No login or key required.","description":"Free, anonymous price-transparency API. Estimates come from insurers' machine-readable rate files and Medicare's fee schedules (Anthem, Blue Cross Blue Shield plans via BlueCard, Blue Shield of California, UnitedHealthcare, Cigna, Aetna, HCSC, Original Medicare) and public CMS data.\n\nRead the guide before relaying numbers to a person: https://api.arlohealth.ai/api/pricing.v1/guide.md\n\nWhat to get from the person, in order of impact: insurer name (required), location (for a named clinic, the clinic's city or ZIP), the exact service (age, new vs established, screening vs symptom, body part, contrast), employer or plan name from the card (turns ranges into exact rates), group number (Blue Cross Blue Shield IL/TX/OK/NM/MT only), provider name or NPI, and from a past bill or Explanation of Benefits the billing NPI and Tax ID (settles which entity bills).\n\nThree rules that apply to every response:\n1. Relay `disclaimer` every time. Estimates are never guarantees, and the number is a negotiated rate, not out-of-pocket cost.\n2. A named clinic, brand, or provider goes to `network-status` first. `search` is area discovery and does not resolve who bills.\n3. Never quote a single number while the billing entity is unresolved (`billingOutlook.mode` = partitioned, `multiEntity` = true, or several `billingCandidates`).\n\nData vintage: 2026-08 payer files.","termsOfService":"https://arlohealth.ai/tos","contact":{"name":"Arlo Health","email":"keaton@arlohealth.ai","url":"https://arlohealth.ai"},"x-agent-guide":"https://api.arlohealth.ai/api/pricing.v1/guide.md","x-skill":"https://api.arlohealth.ai/api/pricing.v1/skill.md","x-disclaimer":"Estimates come from the insurer's published machine-readable rate files (latest monthly data) and are not a guarantee of price. Actual billing can differ based on plan specifics, services performed, and your deductible status. Confirm cost and network status when scheduling."},"externalDocs":{"description":"Agent guide (markdown)","url":"https://api.arlohealth.ai/api/pricing.v1/guide.md"},"servers":[{"url":"https://api.arlohealth.ai","description":"Production"}],"tags":[{"name":"Discovery","description":"Read these first: the guide, the contract, the service catalog, and the supported insurers. Cacheable for an hour."},{"name":"Pricing","description":"The lookups. Anonymous calls are rate limited per IP per minute; a few are served at a time per caller."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Optional. An Arlo account token adds linked-coverage plan matching and family-member patientId. Anonymous calls resolve the plan from planHints only."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]},"SearchRequest":{"type":"object","description":"Area discovery: what does this service cost around here. NOT a clinic directory. The moment the patient names a specific clinic, brand, or provider, use network-status instead.","properties":{"code":{"type":"string","description":"CPT/HCPCS code from the supported catalog. Prices need a code; omit it to receive the catalog as supportedServices in the response (on REST the catalog is also GET /api/pricing.v1/catalog). There is no free-text service input: the caller selects the code, because codes carry patient facts the server cannot infer (screening vs diagnostic intent, age band, new vs established patient, body part, contrast, duration). An unknown code returns 200 with needsMoreInfo plus the full supportedServices catalog."},"latitude":{"type":"number","description":"Preferred when available. Pair with longitude."},"longitude":{"type":"number"},"zip":{"type":"string","description":"5-digit US ZIP when coordinates are unavailable."},"radiusKm":{"type":"number","description":"Search radius in km (default 40)."},"limit":{"type":"number","description":"Max facilities to return (default 25). Also widens the fetched provider pool (up to 80 providers)."},"planHints":{"type":"object","description":"Insurance identifiers from the patient. For anonymous calls this is the ONLY plan input: pass at least payerName (see GET /api/pricing.v1/payers for accepted names). employerName / planName upgrade range estimates to the exact plan's rates when they match a published plan; Group # is only matched for Blue Cross Blue Shield of IL/TX/OK/NM/MT (HCSC). Original Medicare needs no other identifier. Set unavailable=true when the patient cannot provide identifiers, which suppresses further asks and keeps range-based estimates.","properties":{"payerName":{"type":"string","description":"Insurer as the patient names it (e.g. \"Anthem\", \"Blue Shield of California\", \"UnitedHealthcare\", \"Cigna\", \"Aetna\", any Blue Cross Blue Shield plan, \"Original Medicare\"). A bare \"Medicare\" is priced as Original Medicare with a medicare_type ask; Medicare Advantage plans (an insurer's name next to Medicare, HMO/PPO, Part C) are declined with the reason."},"employerName":{"type":"string","description":"Employer the insurance is through, as printed on the card or known to the patient."},"planName":{"type":"string","description":"Plan name printed on the insurance card."},"groupNumber":{"type":"string","description":"Group # exactly as printed on the card. Matches the exact plan for HCSC (BCBS IL/TX/OK/NM/MT) members; other payers do not publish it."},"unavailable":{"type":"boolean","description":"true when the patient cannot provide plan identifiers. Stops plan asks; estimates stay range-based."}}},"patientId":{"type":"string","description":"Family-member patient id on the caller's account. Authenticated calls only: anonymous calls that pass it receive a needsMoreInfo 'auth' ask."}},"required":[]},"SearchResponse":{"type":"object","properties":{"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"supportedServices":{"type":"array","description":"Full pricing catalog, returned when the service could not be resolved. Pick the right code and re-call.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}}}},"plan":{"type":"object","description":"What the estimate is based on. Always read matchTier and basis before relaying numbers.","properties":{"payer":{"type":["string","null"],"description":"Payer key (anthem | blueshield_ca | uhc | cigna | aetna | hcsc | medicare). null when no supported insurer could be identified (matchTier no_payer), including Medicare Advantage plans: read needsMoreInfo for what to tell the patient."},"payerLabel":{"type":["string","null"],"description":"Display name for the payer."},"matchTier":{"type":"string","description":"ein_exact | employer_exact | plan_name_exact | group_exact (the exact plan was found: rate is its negotiated rate) | payer_fallback_unbacked (the exact plan was found, but Arlo does not have that plan's own rate files yet: ranges only, and asking for more identifiers will not help) | payer_fallback (insurer known, plan not identified: ranges across the insurer's plans) | medicare_schedule (Original Medicare: rate is Medicare's approved amount for the provider's locality, and the top-level medicare block plus per-provider patientShare say what the person owes) | no_payer (no supported insurer)"},"basis":{"type":"string","description":"Human-readable explanation of what the estimate is based on. Relay it."},"sponsor":{"type":["string","null"],"description":"Matched plan's identity string. May carry the plan-type token (HMO vs PPO) on group-keyed plans; plan type routinely flips the same hospital between in- and out-of-network, so relay it."},"planTypeNote":{"type":["string","null"],"description":"Present when sponsor carries a plan-type token (HMO, PPO, EPO, POS). Relay it: plan type decides network status."},"payerSource":{"type":"string","description":"'hint' (planHints.payerName) or 'linked_coverage' (the authenticated patient's linked insurance records)."},"coverageSelection":{"type":"object","description":"Authenticated calls only. Present when linked records carry more than one active coverage row: {payor, activeRows}. Relay which coverage was used; pass planHints.payerName to pin a different one."},"coverageNote":{"type":"string","description":"Present when Arlo is missing part of the matched plan's network files. Relay it: providers reachable only through those networks may be absent, and 'not found' is a weaker out-of-network signal."},"planHintsReceived":{"type":"object","description":"Present when planHints were passed: {matched, matchedOn?, reason?}. matched=true only when one of the caller's hints selected the plan; matched=false means do not re-ask the patient for the same value."}}},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}},"geo":{"type":"object","properties":{"source":{"type":"string"}}},"facilities":{"type":"array","description":"Places of care, best rate first. Each groups the billing NPIs at one street address. Present results place-first (facility name or address) with the providers inside.","items":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Organization billing at this address, or (nameSource=billing_entity) the single contracting entity every clinician here bills under; null = independent practitioners, refer to the place by its address or ZIP."},"nameSource":{"type":["string","null"],"description":"'organization_npi' = an organization NPI at this address | 'billing_entity' = inferred from the providers' shared contracting entity (the group the patient books with, not necessarily the sign on the door)."},"address":{"type":["string","null"],"description":"Street address when the index carries one; null with locationPrecision=zip_centroid means only the ZIP is known — say the ZIP/area, never invent a street."},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"latitude":{"type":["number","null"],"description":"Coordinates for rendering on a map. Check locationPrecision."},"longitude":{"type":["number","null"]},"locationPrecision":{"type":["string","null"],"description":"'address' = geocoded street address (map-grade pin) | 'zip_centroid' = one shared point for the whole ZIP (approximate area only)."},"distanceKm":{"type":["number","null"],"description":"Approximate."},"distanceNote":{"type":["string","null"]},"observedServiceBilling":{"type":["boolean","null"],"description":"true when at least one provider here shows observed billing for this service in public claims data."},"activityNote":{"type":["string","null"],"description":"No provider here shows observed billing in public claims data. Payer files list outdated locations for years, so verify the location is operating before sending the patient."},"identityNote":{"type":["string","null"],"description":"Present when this facility's organization name covers several places of DIFFERENT kinds in these results (the hospital, its FQHC subpart, student health). Says which kind this place is. A cheaper same-name subpart is not the hospital; confirm it is the place the patient means before relying on its rate."},"providers":{"type":"array","description":"Billing NPIs at this address with their individual contracted rates, cheapest first. A contracted rate proves the code is in that NPI's network contract, NOT that the service is bookable here; advise confirming when scheduling.","items":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"],"description":"Legal name; null when the index carries none for the NPI."},"entityType":{"type":"string","description":"organization | individual. An organization (imaging center, clinic) is a stronger signal the service is actually offered here than a lone individual NPI."},"facilityType":{"type":["string","null"],"description":"What kind of entity this NPI is, from its NPPES taxonomy (e.g. 'Hospitals / General Acute Care Hospital', 'Ambulatory Health Care Facilities / Clinic/Center / Federally Qualified Health Center (FQHC)'). Say it when several entities share a name."},"specialtyFit":{"type":["string","null"],"description":"How the entity's registered NPPES specialty fits the requested service: 'expected' = a discipline that delivers it; 'unusual' = a different discipline, or a pediatric/student-health entity priced for a non-pediatric service (relay specialtyFitNote). Absent = no basis for a verdict (generic hospital/clinic entity, no taxonomy, or a category any clinician bills). A label and a within-tier sort key, never a filter: the rate is real contract data."},"specialtyFitNote":{"type":["string","null"],"description":"Present with specialtyFit=unusual: what to confirm before relying on the rate."},"parentOrganization":{"type":["string","null"],"description":"NPPES parent organization when this NPI is a subpart of a larger system."},"subpart":{"type":["boolean","null"],"description":"true = an NPPES organization subpart (a department, site, or service line of parentOrganization), not the system itself."},"inNetwork":{"type":"boolean"},"rate":{"type":["number","null"],"description":"Exact-plan negotiated rate; null on fallback matches. On Original Medicare, the approved amount (see medicareAnchor.source and patientShare)."},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateSampled":{"type":["boolean","null"],"description":"true = this provider's schedules were evenly SAMPLED under the fetch budget (see top-level rateFetchNote): its range is indicative, not the full spread. Relay as approximate."},"setting":{"type":["string","null"],"description":"office | facility"},"note":{"type":["string","null"],"description":"Per-provider caveat (e.g. facility-billed rate excludes the physician's separate professional fee). Relay when present."},"rangeNote":{"type":["string","null"],"description":"Present when rateRange spans 3x or more. Relay it: lead with the median or typicalRate, never the minimum."},"patientShare":{"type":["object","null"],"description":"Original Medicare only: what the person owes for this service at the approved amount. afterDeductible is the coinsurance once the year's Part B deductible is met; beforeDeductibleMet is the most they owe if it is not; limitingChargeMax is set only for non-participating providers (the approved amount plus 15%). 0 on screening benefits and clinical lab tests. Relay the note.","properties":{"afterDeductible":{"type":"number"},"beforeDeductibleMet":{"type":"number"},"limitingChargeMax":{"type":["number","null"]},"note":{"type":"string"}}},"medicareStatus":{"type":["object","null"],"description":"Original Medicare only: how the network answer was derived. basis 'cms_enrollment' (the CMS clinician file; assignment 'participating' = accepts the approved amount as payment in full, 'non_participating' = may bill up to 15% more, null = not recorded) | 'observed_billing' (bills Medicare per public claims, assignment unknown) | 'opt_out' (Medicare pays nothing; private contract) | 'no_record' (not a verdict). Relay the accompanying note.","properties":{"enrolled":{"type":["boolean","null"]},"assignment":{"type":["string","null"],"description":"participating | non_participating | null"},"optedOut":{"type":"boolean"},"basis":{"type":"string","description":"cms_enrollment | observed_billing | opt_out | no_record"}}},"statusNote":{"type":["string","null"],"description":"Original Medicare only: the enrollment/assignment sentence to relay."},"typicalRate":{"type":["number","null"],"description":"Median in-network rate for this service among this payer's members."},"rateAssessment":{"type":["string","null"],"description":"Set when the rate is far from typical (>=1.75x or <=0.4x). ALWAYS relay when present."},"serviceEvidence":{"type":["string","null"],"description":"Observed-billing evidence from public Medicare claims data: 'observed' = this NPI actually bills this service | 'category_observed' = bills near-identical services, very likely performs it | 'unconfirmed' = no billing record found. Relay serviceAvailabilityNote and advise confirming; NEVER say they don't offer it (the data misses non-Medicare practices)."},"serviceAvailabilityNote":{"type":["string","null"],"description":"Relay when present."},"telehealthEligible":{"type":"boolean"},"confidence":{"type":"string","description":"high | medium"},"billingOrg":{"type":["string","null"],"description":"Legal entity whose contract the displayed rate belongs to. Often differs from the consumer brand on the door."},"multiEntity":{"type":["boolean","null"],"description":"true = this NPI prices under MULTIPLE contracting entities in this plan and the displayed rate is only the cheapest candidate. Use network-status on this provider to see all candidates before quoting a price."},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchor":{"type":["object","null"],"description":"Medicare reference point. source 'observed' = what Medicare actually paid THIS provider; 'schedule' = Medicare's published fee-schedule rate for the provider's AREA (phrase it as the area rate). A reference point, not the patient's price and not a fair-price claim.","properties":{"source":{"type":"string","description":"observed | schedule"},"medicareAllowed":{"type":"number"},"rateRatio":{"type":["number","null"],"description":"Displayed rate divided by the Medicare amount."},"year":{"type":["number","null"]},"setting":{"type":["string","null"]}}}}}}}}},"totalFound":{"type":"number","description":"Eligible in-network providers for this service in the search area. facilities is the nearest subset with usable rates."},"medicare":{"type":"object","description":"Present on Original Medicare responses. The year's Part B deductible, coinsurance, and limiting charge, whether a Medigap supplement was mentioned, and assumed=true when the person said only \"Medicare\" (confirm it is not an Advantage plan; the medicare_type ask says how). Relay the note once.","properties":{"coverage":{"type":"string","description":"original"},"assumed":{"type":"boolean"},"year":{"type":"number"},"partBDeductible":{"type":"number"},"coinsurancePct":{"type":"number"},"limitingChargePct":{"type":"number"},"medigap":{"type":"boolean"},"note":{"type":"string"}}},"rateFetchNote":{"type":"string","description":"Present when the response is bounded: schedules were sampled evenly (rateSampled=true on affected rows) and/or results cover only the nearest subset of a much larger eligible pool. Relay it: the page is the nearest options, not the area's full price picture."},"multiEntityNote":{"type":["string","null"],"description":"Present once when any provider row is multiEntity: the displayed rate is that provider's group-contract rate and billing may route through an affiliated organization at a different rate. Never quote one number for such a row; resolve via check_network_status."},"sortBasis":{"type":"string","description":"The ordering contract: price within evidence tiers (places with observed billing first, each tier cheapest-first). A cheaper unconfirmed option can sit below confirmed performers; say so when relaying order."},"signalDefinitions":{"type":"object","description":"Once-per-response legend explaining each signal type."},"methodology":{"type":"string","description":"Path to the methodology page."},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"dataVintage":{"type":"string"}}},"NetworkStatusRequest":{"type":"object","description":"Whether a specific provider or facility is in-network for the plan, and optionally what they charge for a service. Call this FIRST for any named clinic, brand, facility, or provider: the billing-entity fork (same visit, very different rates by contracting entity) only surfaces here.","properties":{"providerName":{"type":"string","description":"Provider or facility name. Consumer brand names work (matched against NPPES doing-business-as records too). City or ZIP helps disambiguate."},"npi":{"type":"string","description":"10-digit NPI if known. Never required."},"code":{"type":"string","description":"Optional. CPT/HCPCS code from the supported catalog. Prices need a code; omit it to receive the catalog as supportedServices in the response (on REST the catalog is also GET /api/pricing.v1/catalog). There is no free-text service input: the caller selects the code, because codes carry patient facts the server cannot infer (screening vs diagnostic intent, age band, new vs established patient, body part, contrast, duration). An unknown code returns 200 with needsMoreInfo plus the full supportedServices catalog. With a code, each match carries its contracted rate under the plan."},"limit":{"type":"number","description":"Max matches (default 50, max 100). Large systems bill under many NPIs whose network status and rates differ; the breadth is the signal."},"latitude":{"type":"number","description":"Preferred when available. Pair with longitude."},"longitude":{"type":"number"},"zip":{"type":"string","description":"5-digit US ZIP when coordinates are unavailable."},"planHints":{"type":"object","description":"Insurance identifiers from the patient. For anonymous calls this is the ONLY plan input: pass at least payerName (see GET /api/pricing.v1/payers for accepted names). employerName / planName upgrade range estimates to the exact plan's rates when they match a published plan; Group # is only matched for Blue Cross Blue Shield of IL/TX/OK/NM/MT (HCSC). Original Medicare needs no other identifier. Set unavailable=true when the patient cannot provide identifiers, which suppresses further asks and keeps range-based estimates.","properties":{"payerName":{"type":"string","description":"Insurer as the patient names it (e.g. \"Anthem\", \"Blue Shield of California\", \"UnitedHealthcare\", \"Cigna\", \"Aetna\", any Blue Cross Blue Shield plan, \"Original Medicare\"). A bare \"Medicare\" is priced as Original Medicare with a medicare_type ask; Medicare Advantage plans (an insurer's name next to Medicare, HMO/PPO, Part C) are declined with the reason."},"employerName":{"type":"string","description":"Employer the insurance is through, as printed on the card or known to the patient."},"planName":{"type":"string","description":"Plan name printed on the insurance card."},"groupNumber":{"type":"string","description":"Group # exactly as printed on the card. Matches the exact plan for HCSC (BCBS IL/TX/OK/NM/MT) members; other payers do not publish it."},"unavailable":{"type":"boolean","description":"true when the patient cannot provide plan identifiers. Stops plan asks; estimates stay range-based."}}},"patientId":{"type":"string","description":"Family-member patient id on the caller's account. Authenticated calls only: anonymous calls that pass it receive a needsMoreInfo 'auth' ask."}},"required":[]},"NetworkStatusResponse":{"type":"object","properties":{"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"supportedServices":{"type":"array","description":"Full pricing catalog, returned when the service could not be resolved. Pick the right code and re-call.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}}}},"location":{"type":"object","description":"Whether the ZIP/coordinates passed were consumed. Only re-ask the patient for location when applied=false.","properties":{"applied":{"type":"boolean"},"source":{"type":["string","null"]}}},"matches":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"],"description":"Legal billing name; null when the index carries no name for the NPI (refer to it by NPI)."},"entityType":{"type":"string","description":"organization | individual"},"otherNames":{"type":["array","null"],"items":{"type":"string"},"description":"NPPES doing-business-as names (consumer brands, e.g. 'One Medical')."},"employers":{"type":["array","null"],"description":"CMS-enrolled group affiliations (the groups this clinician reassigns billing to).","items":{"type":"object","properties":{"organization":{"type":["string","null"]},"npi":{"type":["number","string","null"]},"address":{"type":["string","null"]},"telehealth":{"type":["string","boolean","null"]}}}},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"locationPrecision":{"type":["string","null"],"description":"'address' | 'zip_centroid'"},"distanceKm":{"type":["number","null"],"description":"Approximate km from the given location; present only when one was given. Far same-name organizations stay in the list for breadth, so check it before calling a match local."},"facilityType":{"type":["string","null"],"description":"What kind of entity this NPI is, from its NPPES taxonomy (grouping / classification / specialization). Dozens of NPIs can share one legal name (a hospital, its FQHC subpart, student health, a clinic pharmacy); this tells them apart. Relay it when the name is shared."},"specialtyFit":{"type":["string","null"],"description":"How the entity's registered NPPES specialty fits the requested service: 'expected' = a discipline that delivers it; 'unusual' = a different discipline, or a pediatric/student-health entity priced for a non-pediatric service (relay specialtyFitNote). Absent = no basis for a verdict (generic hospital/clinic entity, no taxonomy, or a category any clinician bills). A label and a within-tier sort key, never a filter: the rate is real contract data."},"specialtyFitNote":{"type":["string","null"],"description":"Present with specialtyFit=unusual: what to confirm before relying on the rate."},"taxonomy":{"type":["string","null"],"description":"NPPES primary taxonomy code."},"taxonomyDescription":{"type":["string","null"]},"subpart":{"type":["boolean","null"],"description":"true = an NPPES organization subpart of parentOrganization (a site, department, or service line), not the system itself."},"parentOrganization":{"type":["string","null"],"description":"NPPES parent organization for subparts."},"mailingState":{"type":["string","null"],"description":"Present only when the NPI's mailing (billing office) state differs from its practice state — an HQ or billing-office record rather than a clinic."},"deactivated":{"type":["string","null"],"description":"NPPES deactivation date when the NPI is deactivated. Do not send anyone there."},"identityNote":{"type":["string","null"],"description":"Present when this legal name covers several billing entities of DIFFERENT kinds in the results. Says which kind and address this one is. Confirm it is the place the patient means before relying on its rate."},"attributionNote":{"type":["string","null"],"description":"Present only on providers whose index entry predates NPI-grain billing attribution: candidates may include unrelated practices that merely share a roster group. Treat evidence-less extra candidates as noise."},"identityCaution":{"type":["string","null"],"description":"A same-name person far from the given location. Verify it is the intended provider before relaying anything."},"inNetwork":{"type":"boolean","description":"true = appears WITH negotiated rates in the plan's published network files. false = not found in the published files; read note for how strong that signal is. Never state a hard 'out of network'."},"networkEvidence":{"type":"number","description":"How many of the plan's network memberships back the in-network claim. 1-2 = thin, 10+ = broad participation."},"note":{"type":"string"},"matchNote":{"type":["string","null"],"description":"Present on matches appended by re-searching the name WITHIN the plan's files (fires when the regular name matches are all outside the plan). Often the system's main billing entity at another location; verify identity before relying on it."},"rate":{"type":["number","null"],"description":"Exact-plan negotiated rate for the requested service; null on fallback matches. On Original Medicare, the approved amount."},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateSampled":{"type":["boolean","null"]},"rateNote":{"type":["string","null"],"description":"In-network but the plan's published files carry no rate for this code. Relay; do not read a missing rate as 'not covered'. On Original Medicare it carries the facility-setting caveat or the code's medicareNote."},"rangeNote":{"type":["string","null"],"description":"Present when rateRange spans 3x or more. Relay it: lead with the median or typicalRate, never the minimum."},"patientShare":{"type":["object","null"],"description":"Original Medicare only: what the person owes for this service at the approved amount. afterDeductible is the coinsurance once the year's Part B deductible is met; beforeDeductibleMet is the most they owe if it is not; limitingChargeMax is set only for non-participating providers (the approved amount plus 15%). 0 on screening benefits and clinical lab tests. Relay the note.","properties":{"afterDeductible":{"type":"number"},"beforeDeductibleMet":{"type":"number"},"limitingChargeMax":{"type":["number","null"]},"note":{"type":"string"}}},"medicareStatus":{"type":["object","null"],"description":"Original Medicare only: how the network answer was derived. basis 'cms_enrollment' (the CMS clinician file; assignment 'participating' = accepts the approved amount as payment in full, 'non_participating' = may bill up to 15% more, null = not recorded) | 'observed_billing' (bills Medicare per public claims, assignment unknown) | 'opt_out' (Medicare pays nothing; private contract) | 'no_record' (not a verdict). Relay the accompanying note.","properties":{"enrolled":{"type":["boolean","null"]},"assignment":{"type":["string","null"],"description":"participating | non_participating | null"},"optedOut":{"type":"boolean"},"basis":{"type":"string","description":"cms_enrollment | observed_billing | opt_out | no_record"}}},"setting":{"type":["string","null"],"description":"office | facility; null when no usable published rate backs the match."},"typicalRate":{"type":["number","null"]},"rateAssessment":{"type":["string","null"],"description":"Set when the rate is far from typical. ALWAYS relay; flags invisible markups like hospital-contract billing of routine visits."},"serviceEvidence":{"type":["string","null"],"description":"Observed-billing evidence from public Medicare claims data: 'observed' = this NPI actually bills this service | 'category_observed' = bills near-identical services, very likely performs it | 'unconfirmed' = no billing record found. Relay serviceAvailabilityNote and advise confirming; NEVER say they don't offer it (the data misses non-Medicare practices)."},"serviceAvailabilityNote":{"type":["string","null"],"description":"Relay when present."},"billingOrg":{"type":["string","null"]},"multiEntity":{"type":["boolean","null"]},"billingOutlook":{"type":["object","null"],"description":"Read this FIRST on a rated match. mode 'single' (one entity, quote it), 'resolved' / 'likely' (a leading entity with its evidence basis: lead with it, mention alternatives), or 'partitioned' (the price is a decision tree on WHO BILLS: relay the 'ask' in patient-answerable terms, walk the branch their answer selects, and NEVER quote one number while partitioned). A 'warning' is binding: a brand-name match does not establish the biller.","properties":{"mode":{"type":"string","description":"single | resolved | likely | partitioned"},"ask":{"type":["string","null"],"description":"What resolves the fork: whose name (billing provider, NPI, or Tax ID) is on a past EOB or bill from this practice. Booking location or brand alone does not decide it, except where the brand's own disclosure is office-scoped (then the ask says which office)."},"warning":{"type":["string","null"]},"partnership":{"type":["string","null"],"description":"The brand's own disclosure of which entity bills, when known."},"leading":{"type":["string","null"],"description":"Legal name of the leading billing entity (modes single/resolved/likely); null while partitioned."},"rate":{"anyOf":[{"type":"number"},{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},{"type":"null"}],"description":"The leading entity's rate or range."},"basis":{"type":["string","null"]},"caution":{"type":["string","null"]},"nominated":{"type":["array","null"],"items":{"type":"object","properties":{"entity":{"type":"string"},"basis":{"type":"string"}}},"description":"Partitioned only: candidate entities with the evidence type(s) nominating each."},"brandLeadSuppressed":{"type":["object","null"],"properties":{"entity":{"type":"string"},"reason":{"type":"string"}}}}},"billingCandidates":{"type":["array","null"],"description":"The rate for this clinician grouped by CONTRACTING ENTITY (billing org TIN), cheapest first. Candidates come from the entities on THIS provider's own roster rows in the payer's files, plus entities linked by CMS enrollment, the payer's directory, the brand's own disclosure, or observed claims; never from merely sharing a network roster group. More than one candidate means the same visit prices differently depending on which legal entity bills it. The files cannot say which entity a given booking will bill: surface the fork and resolve the entity from the name, NPI, or Tax ID on a past EOB or bill before quoting one number.","items":{"type":"object","properties":{"billingOrg":{"type":["string","null"],"description":"Legal/business name of the contracting entity, from the payer's files."},"tin":{"type":["string","null"],"description":"The entity's tax id (billing org identity)."},"rate":{"type":["number","null"]},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateNote":{"type":["string","null"],"description":"Why a range is shown instead of a rate."},"setting":{"type":["string","null"],"description":"office | facility; null when the candidate has no usable published rows."},"nMemberships":{"type":"number","description":"How many of the plan's network files price this NPI under this entity."},"typicalRate":{"type":["number","null"]},"rateAssessment":{"type":["string","null"],"description":"Always relay when present."},"evidence":{"type":"array","items":{"type":"object"},"description":"Evidence tags: observed (real adjudicated claims from linked patients; carries n and last date; the only tag that RESOLVES the fork) | payer_credentialed (the payer's own directory, with an as-of date; nominates, never settles) | brand_disclosed | employer | brand_registration."}}}},"billingCandidatesOmitted":{"type":["number","null"],"description":"The candidate list was capped; this many more contracting entities exist."},"billingNote":{"type":["string","null"],"description":"Present when billingCandidates has multiple entities. Relay it; do NOT quote a single rate without resolving the entity."},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchor":{"type":["object","null"],"description":"Medicare reference point. source 'observed' = what Medicare actually paid THIS provider; 'schedule' = Medicare's published fee-schedule rate for the provider's AREA (phrase it as the area rate). A reference point, not the patient's price and not a fair-price claim.","properties":{"source":{"type":"string","description":"observed | schedule"},"medicareAllowed":{"type":"number"},"rateRatio":{"type":["number","null"],"description":"Displayed rate divided by the Medicare amount."},"year":{"type":["number","null"]},"setting":{"type":["string","null"]}}}}}},"organizations":{"type":["array","null"],"description":"Present when several organization matches share a parent organization or legal name. One entry per system with its billing entities grouped and typed, so a large system reads as a tree (hospital, subparts, clinics) rather than a flat list of same-name rows. Entities list nearest first when a location was given (nearestKm on the system, distanceKm per entity); a system's far-away sites are in the tree for breadth, not as the answer to a local question. Present the system, then the entity the patient means.","items":{"type":"object","properties":{"organization":{"type":"string"},"entities":{"type":"number","description":"Billing NPIs matched under this organization."},"inNetwork":{"type":"number","description":"How many of them are in the plan's files."},"nearestKm":{"type":["number","null"],"description":"Distance to the system's nearest matched entity, when a location was given."},"facilityTypes":{"type":"object","description":"facilityType -> count."},"npis":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"number"},"facilityType":{"type":["string","null"]},"city":{"type":["string","null"]},"distanceKm":{"type":["number","null"],"description":"Approximate km from the given location; entries are listed nearest first."},"inNetwork":{"type":"boolean"},"rate":{"type":["number","null"]},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}}}}}}}},"plan":{"type":"object","description":"What the estimate is based on. Always read matchTier and basis before relaying numbers.","properties":{"payer":{"type":["string","null"],"description":"Payer key (anthem | blueshield_ca | uhc | cigna | aetna | hcsc | medicare). null when no supported insurer could be identified (matchTier no_payer), including Medicare Advantage plans: read needsMoreInfo for what to tell the patient."},"payerLabel":{"type":["string","null"],"description":"Display name for the payer."},"matchTier":{"type":"string","description":"ein_exact | employer_exact | plan_name_exact | group_exact (the exact plan was found: rate is its negotiated rate) | payer_fallback_unbacked (the exact plan was found, but Arlo does not have that plan's own rate files yet: ranges only, and asking for more identifiers will not help) | payer_fallback (insurer known, plan not identified: ranges across the insurer's plans) | medicare_schedule (Original Medicare: rate is Medicare's approved amount for the provider's locality, and the top-level medicare block plus per-provider patientShare say what the person owes) | no_payer (no supported insurer)"},"basis":{"type":"string","description":"Human-readable explanation of what the estimate is based on. Relay it."},"sponsor":{"type":["string","null"],"description":"Matched plan's identity string. May carry the plan-type token (HMO vs PPO) on group-keyed plans; plan type routinely flips the same hospital between in- and out-of-network, so relay it."},"planTypeNote":{"type":["string","null"],"description":"Present when sponsor carries a plan-type token (HMO, PPO, EPO, POS). Relay it: plan type decides network status."},"payerSource":{"type":"string","description":"'hint' (planHints.payerName) or 'linked_coverage' (the authenticated patient's linked insurance records)."},"coverageSelection":{"type":"object","description":"Authenticated calls only. Present when linked records carry more than one active coverage row: {payor, activeRows}. Relay which coverage was used; pass planHints.payerName to pin a different one."},"coverageNote":{"type":"string","description":"Present when Arlo is missing part of the matched plan's network files. Relay it: providers reachable only through those networks may be absent, and 'not found' is a weaker out-of-network signal."},"planHintsReceived":{"type":"object","description":"Present when planHints were passed: {matched, matchedOn?, reason?}. matched=true only when one of the caller's hints selected the plan; matched=false means do not re-ask the patient for the same value."}}},"medicare":{"type":"object","description":"Present on Original Medicare responses. The year's Part B deductible, coinsurance, and limiting charge, whether a Medigap supplement was mentioned, and assumed=true when the person said only \"Medicare\" (confirm it is not an Advantage plan; the medicare_type ask says how). Relay the note once.","properties":{"coverage":{"type":"string","description":"original"},"assumed":{"type":"boolean"},"year":{"type":"number"},"partBDeductible":{"type":"number"},"coinsurancePct":{"type":"number"},"limitingChargePct":{"type":"number"},"medigap":{"type":"boolean"},"note":{"type":"string"}}},"rateFetchNote":{"type":"string"},"networkNote":{"type":["string","null"],"description":"Present when every match is outside the plan. Explains why that is not an out-of-network verdict and how to resolve the real billing entity. Relay it before any network verdict."},"billingEvidenceDefinitions":{"type":"object","description":"Once-per-response legend for billingCandidates[].evidence[].type. Present when any match carries billingCandidates."},"evidenceCardEligible":{"type":"boolean","description":"true when exactly one match carries evidence signals (a UI may render an evidence card)."},"signalDefinitions":{"type":"object"},"methodology":{"type":"string"},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."}}},"ProviderEvidenceRequest":{"type":"object","description":"Public-data evidence about ONE specific provider: Medicare-derived experience, facility outcome context (facility-level, never the clinician's own outcome), Medicare payment anchors, or an explained absence. Use only once the conversation is focused on one provider.","properties":{"npi":{"type":"string","description":"The provider's 10-digit NPI. Resolve it first via network-status (name search) or from search results."},"code":{"type":"string","description":"Optional catalog code to scope evidence to one service."}},"required":["npi"]},"ProviderEvidenceResponse":{"type":"object","properties":{"provider":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"]},"entityType":{"type":"string","description":"organization | individual"},"city":{"type":["string","null"]},"state":{"type":["string","null"]}},"required":["npi"]},"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchors":{"type":"array","description":"What Medicare actually paid this provider per service. Reference points from public data, not fair-price claims and not the patient's price.","items":{"type":"object","properties":{"code":{"type":"string"},"setting":{"type":"string","description":"facility | office"},"service":{"type":["string","null"]},"medicareAllowed":{"type":"number"},"year":{"type":"number"}},"required":["code","medicareAllowed","year"]}},"signalDefinitions":{"type":"object"},"methodology":{"type":"string"},"corrections":{"type":"string"},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}}}},"Catalog":{"type":"object","properties":{"version":{"type":"string"},"services":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string"},"priceNote":{"type":["string","null"]},"medicareNote":{"type":["string","null"],"description":"Set on codes Original Medicare does not pay under this code: what it covers instead."},"relatedCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"when":{"type":"string"}}}}},"required":["code","name","category"]}}}},"Payers":{"type":"object","properties":{"payers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Value returned in plan.payer. Identifies the underlying rate corpus, so it is NOT unique across entries. Anthem and BlueCard-routed Blue plans both price from the same files and share a key while differing in label, coverage and acceptedNames. Never key a lookup on it; pass a value from acceptedNames as planHints.payerName."},"label":{"type":"string"},"acceptedNames":{"type":"array","items":{"type":"string"},"description":"Names planHints.payerName recognizes for this payer."},"exactPlanIdentifiers":{"type":"array","items":{"type":"string"},"description":"Which planHints fields can select the exact plan (employerName, planName, groupNumber). Empty for Original Medicare: nothing else is needed."},"coverage":{"type":"string","description":"Where the payer's published files cover."},"blueCard":{"type":"boolean","description":"true for Blue Cross Blue Shield plans outside California, which are priced through the local Blue Cross Blue Shield plan's network wherever the member is."}},"required":["key","label","acceptedNames"]}}}},"Index":{"type":"object","properties":{"name":{"type":"string"},"apiVersion":{"type":"string"},"dataVintage":{"type":"string"},"region":{"type":"string"},"auth":{"type":"string"},"docs":{"type":"object"},"endpoints":{"type":"array","items":{"type":"object"}},"rateLimits":{"type":"object"},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"terms":{"type":"string"},"contact":{"type":"string"}}}}},"security":[{},{"bearerAuth":[]}],"paths":{"/api/pricing.v1":{"get":{"tags":["Discovery"],"operationId":"getIndex","summary":"API index: links to every route, limits, disclaimer","responses":{"200":{"description":"Index","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"apiVersion":{"type":"string"},"dataVintage":{"type":"string"},"region":{"type":"string"},"auth":{"type":"string"},"docs":{"type":"object"},"endpoints":{"type":"array","items":{"type":"object"}},"rateLimits":{"type":"object"},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"terms":{"type":"string"},"contact":{"type":"string"}}}}},"headers":{"X-Arlo-Api-Version":{"schema":{"type":"string"},"description":"Contract version (currently 1)."},"Link":{"schema":{"type":"string"},"description":"rel=\"service-doc\" points at guide.md, rel=\"service-desc\" at openapi.json."}}}}}},"/api/pricing.v1/openapi.json":{"get":{"tags":["Discovery"],"operationId":"getOpenApiJson","summary":"This document (JSON)","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/pricing.v1/openapi.yaml":{"get":{"tags":["Discovery"],"operationId":"getOpenApiYaml","summary":"This document (YAML)","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/yaml":{"schema":{"type":"string"}}}}}}},"/api/pricing.v1/guide.md":{"get":{"tags":["Discovery"],"operationId":"getGuide","summary":"Agent guide: how to call these routes and how to read every field","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/api/pricing.v1/skill.md":{"get":{"tags":["Discovery"],"operationId":"getSkill","summary":"Drop-in SKILL.md for agent platforms (Grok Bot, Claude, Codex)","responses":{"200":{"description":"Markdown","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/api/pricing.v1/catalog":{"get":{"tags":["Discovery"],"operationId":"getCatalog","summary":"Supported services (CPT/HCPCS codes) with appliesTo and relatedCodes","responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"services":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string"},"priceNote":{"type":["string","null"]},"medicareNote":{"type":["string","null"],"description":"Set on codes Original Medicare does not pay under this code: what it covers instead."},"relatedCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"when":{"type":"string"}}}}},"required":["code","name","category"]}}}}}}}}},"post":{"tags":["Discovery"],"operationId":"postCatalog","summary":"Same as GET (kept for older clients)","responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"services":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string"},"priceNote":{"type":["string","null"]},"medicareNote":{"type":["string","null"],"description":"Set on codes Original Medicare does not pay under this code: what it covers instead."},"relatedCodes":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"when":{"type":"string"}}}}},"required":["code","name","category"]}}}}}}}}}},"/api/pricing.v1/payers":{"get":{"tags":["Discovery"],"operationId":"getPayers","summary":"Supported insurers and the names planHints.payerName accepts","responses":{"200":{"description":"Payers","content":{"application/json":{"schema":{"type":"object","properties":{"payers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Value returned in plan.payer. Identifies the underlying rate corpus, so it is NOT unique across entries. Anthem and BlueCard-routed Blue plans both price from the same files and share a key while differing in label, coverage and acceptedNames. Never key a lookup on it; pass a value from acceptedNames as planHints.payerName."},"label":{"type":"string"},"acceptedNames":{"type":"array","items":{"type":"string"},"description":"Names planHints.payerName recognizes for this payer."},"exactPlanIdentifiers":{"type":"array","items":{"type":"string"},"description":"Which planHints fields can select the exact plan (employerName, planName, groupNumber). Empty for Original Medicare: nothing else is needed."},"coverage":{"type":"string","description":"Where the payer's published files cover."},"blueCard":{"type":"boolean","description":"true for Blue Cross Blue Shield plans outside California, which are priced through the local Blue Cross Blue Shield plan's network wherever the member is."}},"required":["key","label","acceptedNames"]}}}}}}}}}},"/api/pricing.v1/search":{"post":{"tags":["Pricing"],"operationId":"searchCarePrices","summary":"Nearby in-network options with estimated negotiated prices for one service","description":"Area discovery: what does this service cost around here. NOT a clinic directory. The moment the patient names a specific clinic, brand, or provider, use network-status instead. Anonymous limit: 60 requests per minute per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Area discovery: what does this service cost around here. NOT a clinic directory. The moment the patient names a specific clinic, brand, or provider, use network-status instead.","properties":{"code":{"type":"string","description":"CPT/HCPCS code from the supported catalog. Prices need a code; omit it to receive the catalog as supportedServices in the response (on REST the catalog is also GET /api/pricing.v1/catalog). There is no free-text service input: the caller selects the code, because codes carry patient facts the server cannot infer (screening vs diagnostic intent, age band, new vs established patient, body part, contrast, duration). An unknown code returns 200 with needsMoreInfo plus the full supportedServices catalog."},"latitude":{"type":"number","description":"Preferred when available. Pair with longitude."},"longitude":{"type":"number"},"zip":{"type":"string","description":"5-digit US ZIP when coordinates are unavailable."},"radiusKm":{"type":"number","description":"Search radius in km (default 40)."},"limit":{"type":"number","description":"Max facilities to return (default 25). Also widens the fetched provider pool (up to 80 providers)."},"planHints":{"type":"object","description":"Insurance identifiers from the patient. For anonymous calls this is the ONLY plan input: pass at least payerName (see GET /api/pricing.v1/payers for accepted names). employerName / planName upgrade range estimates to the exact plan's rates when they match a published plan; Group # is only matched for Blue Cross Blue Shield of IL/TX/OK/NM/MT (HCSC). Original Medicare needs no other identifier. Set unavailable=true when the patient cannot provide identifiers, which suppresses further asks and keeps range-based estimates.","properties":{"payerName":{"type":"string","description":"Insurer as the patient names it (e.g. \"Anthem\", \"Blue Shield of California\", \"UnitedHealthcare\", \"Cigna\", \"Aetna\", any Blue Cross Blue Shield plan, \"Original Medicare\"). A bare \"Medicare\" is priced as Original Medicare with a medicare_type ask; Medicare Advantage plans (an insurer's name next to Medicare, HMO/PPO, Part C) are declined with the reason."},"employerName":{"type":"string","description":"Employer the insurance is through, as printed on the card or known to the patient."},"planName":{"type":"string","description":"Plan name printed on the insurance card."},"groupNumber":{"type":"string","description":"Group # exactly as printed on the card. Matches the exact plan for HCSC (BCBS IL/TX/OK/NM/MT) members; other payers do not publish it."},"unavailable":{"type":"boolean","description":"true when the patient cannot provide plan identifiers. Stops plan asks; estimates stay range-based."}}},"patientId":{"type":"string","description":"Family-member patient id on the caller's account. Authenticated calls only: anonymous calls that pass it receive a needsMoreInfo 'auth' ask."}},"required":[]},"example":{"code":"99213","zip":"94607","limit":10,"planHints":{"payerName":"Anthem"}}}}},"responses":{"200":{"description":"Search results. Also 200 with needsMoreInfo when the code, location, or insurer could not be resolved.","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"supportedServices":{"type":"array","description":"Full pricing catalog, returned when the service could not be resolved. Pick the right code and re-call.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}}}},"plan":{"type":"object","description":"What the estimate is based on. Always read matchTier and basis before relaying numbers.","properties":{"payer":{"type":["string","null"],"description":"Payer key (anthem | blueshield_ca | uhc | cigna | aetna | hcsc | medicare). null when no supported insurer could be identified (matchTier no_payer), including Medicare Advantage plans: read needsMoreInfo for what to tell the patient."},"payerLabel":{"type":["string","null"],"description":"Display name for the payer."},"matchTier":{"type":"string","description":"ein_exact | employer_exact | plan_name_exact | group_exact (the exact plan was found: rate is its negotiated rate) | payer_fallback_unbacked (the exact plan was found, but Arlo does not have that plan's own rate files yet: ranges only, and asking for more identifiers will not help) | payer_fallback (insurer known, plan not identified: ranges across the insurer's plans) | medicare_schedule (Original Medicare: rate is Medicare's approved amount for the provider's locality, and the top-level medicare block plus per-provider patientShare say what the person owes) | no_payer (no supported insurer)"},"basis":{"type":"string","description":"Human-readable explanation of what the estimate is based on. Relay it."},"sponsor":{"type":["string","null"],"description":"Matched plan's identity string. May carry the plan-type token (HMO vs PPO) on group-keyed plans; plan type routinely flips the same hospital between in- and out-of-network, so relay it."},"planTypeNote":{"type":["string","null"],"description":"Present when sponsor carries a plan-type token (HMO, PPO, EPO, POS). Relay it: plan type decides network status."},"payerSource":{"type":"string","description":"'hint' (planHints.payerName) or 'linked_coverage' (the authenticated patient's linked insurance records)."},"coverageSelection":{"type":"object","description":"Authenticated calls only. Present when linked records carry more than one active coverage row: {payor, activeRows}. Relay which coverage was used; pass planHints.payerName to pin a different one."},"coverageNote":{"type":"string","description":"Present when Arlo is missing part of the matched plan's network files. Relay it: providers reachable only through those networks may be absent, and 'not found' is a weaker out-of-network signal."},"planHintsReceived":{"type":"object","description":"Present when planHints were passed: {matched, matchedOn?, reason?}. matched=true only when one of the caller's hints selected the plan; matched=false means do not re-ask the patient for the same value."}}},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}},"geo":{"type":"object","properties":{"source":{"type":"string"}}},"facilities":{"type":"array","description":"Places of care, best rate first. Each groups the billing NPIs at one street address. Present results place-first (facility name or address) with the providers inside.","items":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Organization billing at this address, or (nameSource=billing_entity) the single contracting entity every clinician here bills under; null = independent practitioners, refer to the place by its address or ZIP."},"nameSource":{"type":["string","null"],"description":"'organization_npi' = an organization NPI at this address | 'billing_entity' = inferred from the providers' shared contracting entity (the group the patient books with, not necessarily the sign on the door)."},"address":{"type":["string","null"],"description":"Street address when the index carries one; null with locationPrecision=zip_centroid means only the ZIP is known — say the ZIP/area, never invent a street."},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"latitude":{"type":["number","null"],"description":"Coordinates for rendering on a map. Check locationPrecision."},"longitude":{"type":["number","null"]},"locationPrecision":{"type":["string","null"],"description":"'address' = geocoded street address (map-grade pin) | 'zip_centroid' = one shared point for the whole ZIP (approximate area only)."},"distanceKm":{"type":["number","null"],"description":"Approximate."},"distanceNote":{"type":["string","null"]},"observedServiceBilling":{"type":["boolean","null"],"description":"true when at least one provider here shows observed billing for this service in public claims data."},"activityNote":{"type":["string","null"],"description":"No provider here shows observed billing in public claims data. Payer files list outdated locations for years, so verify the location is operating before sending the patient."},"identityNote":{"type":["string","null"],"description":"Present when this facility's organization name covers several places of DIFFERENT kinds in these results (the hospital, its FQHC subpart, student health). Says which kind this place is. A cheaper same-name subpart is not the hospital; confirm it is the place the patient means before relying on its rate."},"providers":{"type":"array","description":"Billing NPIs at this address with their individual contracted rates, cheapest first. A contracted rate proves the code is in that NPI's network contract, NOT that the service is bookable here; advise confirming when scheduling.","items":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"],"description":"Legal name; null when the index carries none for the NPI."},"entityType":{"type":"string","description":"organization | individual. An organization (imaging center, clinic) is a stronger signal the service is actually offered here than a lone individual NPI."},"facilityType":{"type":["string","null"],"description":"What kind of entity this NPI is, from its NPPES taxonomy (e.g. 'Hospitals / General Acute Care Hospital', 'Ambulatory Health Care Facilities / Clinic/Center / Federally Qualified Health Center (FQHC)'). Say it when several entities share a name."},"specialtyFit":{"type":["string","null"],"description":"How the entity's registered NPPES specialty fits the requested service: 'expected' = a discipline that delivers it; 'unusual' = a different discipline, or a pediatric/student-health entity priced for a non-pediatric service (relay specialtyFitNote). Absent = no basis for a verdict (generic hospital/clinic entity, no taxonomy, or a category any clinician bills). A label and a within-tier sort key, never a filter: the rate is real contract data."},"specialtyFitNote":{"type":["string","null"],"description":"Present with specialtyFit=unusual: what to confirm before relying on the rate."},"parentOrganization":{"type":["string","null"],"description":"NPPES parent organization when this NPI is a subpart of a larger system."},"subpart":{"type":["boolean","null"],"description":"true = an NPPES organization subpart (a department, site, or service line of parentOrganization), not the system itself."},"inNetwork":{"type":"boolean"},"rate":{"type":["number","null"],"description":"Exact-plan negotiated rate; null on fallback matches. On Original Medicare, the approved amount (see medicareAnchor.source and patientShare)."},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateSampled":{"type":["boolean","null"],"description":"true = this provider's schedules were evenly SAMPLED under the fetch budget (see top-level rateFetchNote): its range is indicative, not the full spread. Relay as approximate."},"setting":{"type":["string","null"],"description":"office | facility"},"note":{"type":["string","null"],"description":"Per-provider caveat (e.g. facility-billed rate excludes the physician's separate professional fee). Relay when present."},"rangeNote":{"type":["string","null"],"description":"Present when rateRange spans 3x or more. Relay it: lead with the median or typicalRate, never the minimum."},"patientShare":{"type":["object","null"],"description":"Original Medicare only: what the person owes for this service at the approved amount. afterDeductible is the coinsurance once the year's Part B deductible is met; beforeDeductibleMet is the most they owe if it is not; limitingChargeMax is set only for non-participating providers (the approved amount plus 15%). 0 on screening benefits and clinical lab tests. Relay the note.","properties":{"afterDeductible":{"type":"number"},"beforeDeductibleMet":{"type":"number"},"limitingChargeMax":{"type":["number","null"]},"note":{"type":"string"}}},"medicareStatus":{"type":["object","null"],"description":"Original Medicare only: how the network answer was derived. basis 'cms_enrollment' (the CMS clinician file; assignment 'participating' = accepts the approved amount as payment in full, 'non_participating' = may bill up to 15% more, null = not recorded) | 'observed_billing' (bills Medicare per public claims, assignment unknown) | 'opt_out' (Medicare pays nothing; private contract) | 'no_record' (not a verdict). Relay the accompanying note.","properties":{"enrolled":{"type":["boolean","null"]},"assignment":{"type":["string","null"],"description":"participating | non_participating | null"},"optedOut":{"type":"boolean"},"basis":{"type":"string","description":"cms_enrollment | observed_billing | opt_out | no_record"}}},"statusNote":{"type":["string","null"],"description":"Original Medicare only: the enrollment/assignment sentence to relay."},"typicalRate":{"type":["number","null"],"description":"Median in-network rate for this service among this payer's members."},"rateAssessment":{"type":["string","null"],"description":"Set when the rate is far from typical (>=1.75x or <=0.4x). ALWAYS relay when present."},"serviceEvidence":{"type":["string","null"],"description":"Observed-billing evidence from public Medicare claims data: 'observed' = this NPI actually bills this service | 'category_observed' = bills near-identical services, very likely performs it | 'unconfirmed' = no billing record found. Relay serviceAvailabilityNote and advise confirming; NEVER say they don't offer it (the data misses non-Medicare practices)."},"serviceAvailabilityNote":{"type":["string","null"],"description":"Relay when present."},"telehealthEligible":{"type":"boolean"},"confidence":{"type":"string","description":"high | medium"},"billingOrg":{"type":["string","null"],"description":"Legal entity whose contract the displayed rate belongs to. Often differs from the consumer brand on the door."},"multiEntity":{"type":["boolean","null"],"description":"true = this NPI prices under MULTIPLE contracting entities in this plan and the displayed rate is only the cheapest candidate. Use network-status on this provider to see all candidates before quoting a price."},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchor":{"type":["object","null"],"description":"Medicare reference point. source 'observed' = what Medicare actually paid THIS provider; 'schedule' = Medicare's published fee-schedule rate for the provider's AREA (phrase it as the area rate). A reference point, not the patient's price and not a fair-price claim.","properties":{"source":{"type":"string","description":"observed | schedule"},"medicareAllowed":{"type":"number"},"rateRatio":{"type":["number","null"],"description":"Displayed rate divided by the Medicare amount."},"year":{"type":["number","null"]},"setting":{"type":["string","null"]}}}}}}}}},"totalFound":{"type":"number","description":"Eligible in-network providers for this service in the search area. facilities is the nearest subset with usable rates."},"medicare":{"type":"object","description":"Present on Original Medicare responses. The year's Part B deductible, coinsurance, and limiting charge, whether a Medigap supplement was mentioned, and assumed=true when the person said only \"Medicare\" (confirm it is not an Advantage plan; the medicare_type ask says how). Relay the note once.","properties":{"coverage":{"type":"string","description":"original"},"assumed":{"type":"boolean"},"year":{"type":"number"},"partBDeductible":{"type":"number"},"coinsurancePct":{"type":"number"},"limitingChargePct":{"type":"number"},"medigap":{"type":"boolean"},"note":{"type":"string"}}},"rateFetchNote":{"type":"string","description":"Present when the response is bounded: schedules were sampled evenly (rateSampled=true on affected rows) and/or results cover only the nearest subset of a much larger eligible pool. Relay it: the page is the nearest options, not the area's full price picture."},"multiEntityNote":{"type":["string","null"],"description":"Present once when any provider row is multiEntity: the displayed rate is that provider's group-contract rate and billing may route through an affiliated organization at a different rate. Never quote one number for such a row; resolve via check_network_status."},"sortBasis":{"type":"string","description":"The ordering contract: price within evidence tiers (places with observed billing first, each tier cheapest-first). A cheaper unconfirmed option can sit below confirmed performers; say so when relaying order."},"signalDefinitions":{"type":"object","description":"Once-per-response legend explaining each signal type."},"methodology":{"type":"string","description":"Path to the methodology page."},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"dataVintage":{"type":"string"}}}}},"headers":{"X-Arlo-Api-Version":{"schema":{"type":"string"},"description":"Contract version (currently 1)."},"Link":{"schema":{"type":"string"},"description":"rel=\"service-doc\" points at guide.md, rel=\"service-desc\" at openapi.json."}}},"429":{"description":"Too many requests: the per-IP limit for this route was exceeded (RATE_LIMITED), or the service is busy (BUSY). Wait Retry-After seconds and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Anonymous pricing is paused. Honor Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}}}}},"get":{"tags":["Pricing"],"operationId":"searchCarePricesGet","summary":"Same as POST with flat query parameters","parameters":[{"name":"code","in":"query","required":false,"schema":{"type":"string"},"description":"Catalog code"},{"name":"zip","in":"query","schema":{"type":"string"},"description":"5-digit US ZIP"},{"name":"latitude","in":"query","schema":{"type":"number"}},{"name":"longitude","in":"query","schema":{"type":"number"}},{"name":"radiusKm","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"payerName","in":"query","schema":{"type":"string"},"description":"planHints.payerName"},{"name":"employerName","in":"query","schema":{"type":"string"},"description":"planHints.employerName"},{"name":"planName","in":"query","schema":{"type":"string"},"description":"planHints.planName"},{"name":"groupNumber","in":"query","schema":{"type":"string"},"description":"planHints.groupNumber (HCSC members only)"},{"name":"planUnavailable","in":"query","schema":{"type":"boolean"},"description":"planHints.unavailable"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"supportedServices":{"type":"array","description":"Full pricing catalog, returned when the service could not be resolved. Pick the right code and re-call.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}}}},"plan":{"type":"object","description":"What the estimate is based on. Always read matchTier and basis before relaying numbers.","properties":{"payer":{"type":["string","null"],"description":"Payer key (anthem | blueshield_ca | uhc | cigna | aetna | hcsc | medicare). null when no supported insurer could be identified (matchTier no_payer), including Medicare Advantage plans: read needsMoreInfo for what to tell the patient."},"payerLabel":{"type":["string","null"],"description":"Display name for the payer."},"matchTier":{"type":"string","description":"ein_exact | employer_exact | plan_name_exact | group_exact (the exact plan was found: rate is its negotiated rate) | payer_fallback_unbacked (the exact plan was found, but Arlo does not have that plan's own rate files yet: ranges only, and asking for more identifiers will not help) | payer_fallback (insurer known, plan not identified: ranges across the insurer's plans) | medicare_schedule (Original Medicare: rate is Medicare's approved amount for the provider's locality, and the top-level medicare block plus per-provider patientShare say what the person owes) | no_payer (no supported insurer)"},"basis":{"type":"string","description":"Human-readable explanation of what the estimate is based on. Relay it."},"sponsor":{"type":["string","null"],"description":"Matched plan's identity string. May carry the plan-type token (HMO vs PPO) on group-keyed plans; plan type routinely flips the same hospital between in- and out-of-network, so relay it."},"planTypeNote":{"type":["string","null"],"description":"Present when sponsor carries a plan-type token (HMO, PPO, EPO, POS). Relay it: plan type decides network status."},"payerSource":{"type":"string","description":"'hint' (planHints.payerName) or 'linked_coverage' (the authenticated patient's linked insurance records)."},"coverageSelection":{"type":"object","description":"Authenticated calls only. Present when linked records carry more than one active coverage row: {payor, activeRows}. Relay which coverage was used; pass planHints.payerName to pin a different one."},"coverageNote":{"type":"string","description":"Present when Arlo is missing part of the matched plan's network files. Relay it: providers reachable only through those networks may be absent, and 'not found' is a weaker out-of-network signal."},"planHintsReceived":{"type":"object","description":"Present when planHints were passed: {matched, matchedOn?, reason?}. matched=true only when one of the caller's hints selected the plan; matched=false means do not re-ask the patient for the same value."}}},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}},"geo":{"type":"object","properties":{"source":{"type":"string"}}},"facilities":{"type":"array","description":"Places of care, best rate first. Each groups the billing NPIs at one street address. Present results place-first (facility name or address) with the providers inside.","items":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Organization billing at this address, or (nameSource=billing_entity) the single contracting entity every clinician here bills under; null = independent practitioners, refer to the place by its address or ZIP."},"nameSource":{"type":["string","null"],"description":"'organization_npi' = an organization NPI at this address | 'billing_entity' = inferred from the providers' shared contracting entity (the group the patient books with, not necessarily the sign on the door)."},"address":{"type":["string","null"],"description":"Street address when the index carries one; null with locationPrecision=zip_centroid means only the ZIP is known — say the ZIP/area, never invent a street."},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"latitude":{"type":["number","null"],"description":"Coordinates for rendering on a map. Check locationPrecision."},"longitude":{"type":["number","null"]},"locationPrecision":{"type":["string","null"],"description":"'address' = geocoded street address (map-grade pin) | 'zip_centroid' = one shared point for the whole ZIP (approximate area only)."},"distanceKm":{"type":["number","null"],"description":"Approximate."},"distanceNote":{"type":["string","null"]},"observedServiceBilling":{"type":["boolean","null"],"description":"true when at least one provider here shows observed billing for this service in public claims data."},"activityNote":{"type":["string","null"],"description":"No provider here shows observed billing in public claims data. Payer files list outdated locations for years, so verify the location is operating before sending the patient."},"identityNote":{"type":["string","null"],"description":"Present when this facility's organization name covers several places of DIFFERENT kinds in these results (the hospital, its FQHC subpart, student health). Says which kind this place is. A cheaper same-name subpart is not the hospital; confirm it is the place the patient means before relying on its rate."},"providers":{"type":"array","description":"Billing NPIs at this address with their individual contracted rates, cheapest first. A contracted rate proves the code is in that NPI's network contract, NOT that the service is bookable here; advise confirming when scheduling.","items":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"],"description":"Legal name; null when the index carries none for the NPI."},"entityType":{"type":"string","description":"organization | individual. An organization (imaging center, clinic) is a stronger signal the service is actually offered here than a lone individual NPI."},"facilityType":{"type":["string","null"],"description":"What kind of entity this NPI is, from its NPPES taxonomy (e.g. 'Hospitals / General Acute Care Hospital', 'Ambulatory Health Care Facilities / Clinic/Center / Federally Qualified Health Center (FQHC)'). Say it when several entities share a name."},"specialtyFit":{"type":["string","null"],"description":"How the entity's registered NPPES specialty fits the requested service: 'expected' = a discipline that delivers it; 'unusual' = a different discipline, or a pediatric/student-health entity priced for a non-pediatric service (relay specialtyFitNote). Absent = no basis for a verdict (generic hospital/clinic entity, no taxonomy, or a category any clinician bills). A label and a within-tier sort key, never a filter: the rate is real contract data."},"specialtyFitNote":{"type":["string","null"],"description":"Present with specialtyFit=unusual: what to confirm before relying on the rate."},"parentOrganization":{"type":["string","null"],"description":"NPPES parent organization when this NPI is a subpart of a larger system."},"subpart":{"type":["boolean","null"],"description":"true = an NPPES organization subpart (a department, site, or service line of parentOrganization), not the system itself."},"inNetwork":{"type":"boolean"},"rate":{"type":["number","null"],"description":"Exact-plan negotiated rate; null on fallback matches. On Original Medicare, the approved amount (see medicareAnchor.source and patientShare)."},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateSampled":{"type":["boolean","null"],"description":"true = this provider's schedules were evenly SAMPLED under the fetch budget (see top-level rateFetchNote): its range is indicative, not the full spread. Relay as approximate."},"setting":{"type":["string","null"],"description":"office | facility"},"note":{"type":["string","null"],"description":"Per-provider caveat (e.g. facility-billed rate excludes the physician's separate professional fee). Relay when present."},"rangeNote":{"type":["string","null"],"description":"Present when rateRange spans 3x or more. Relay it: lead with the median or typicalRate, never the minimum."},"patientShare":{"type":["object","null"],"description":"Original Medicare only: what the person owes for this service at the approved amount. afterDeductible is the coinsurance once the year's Part B deductible is met; beforeDeductibleMet is the most they owe if it is not; limitingChargeMax is set only for non-participating providers (the approved amount plus 15%). 0 on screening benefits and clinical lab tests. Relay the note.","properties":{"afterDeductible":{"type":"number"},"beforeDeductibleMet":{"type":"number"},"limitingChargeMax":{"type":["number","null"]},"note":{"type":"string"}}},"medicareStatus":{"type":["object","null"],"description":"Original Medicare only: how the network answer was derived. basis 'cms_enrollment' (the CMS clinician file; assignment 'participating' = accepts the approved amount as payment in full, 'non_participating' = may bill up to 15% more, null = not recorded) | 'observed_billing' (bills Medicare per public claims, assignment unknown) | 'opt_out' (Medicare pays nothing; private contract) | 'no_record' (not a verdict). Relay the accompanying note.","properties":{"enrolled":{"type":["boolean","null"]},"assignment":{"type":["string","null"],"description":"participating | non_participating | null"},"optedOut":{"type":"boolean"},"basis":{"type":"string","description":"cms_enrollment | observed_billing | opt_out | no_record"}}},"statusNote":{"type":["string","null"],"description":"Original Medicare only: the enrollment/assignment sentence to relay."},"typicalRate":{"type":["number","null"],"description":"Median in-network rate for this service among this payer's members."},"rateAssessment":{"type":["string","null"],"description":"Set when the rate is far from typical (>=1.75x or <=0.4x). ALWAYS relay when present."},"serviceEvidence":{"type":["string","null"],"description":"Observed-billing evidence from public Medicare claims data: 'observed' = this NPI actually bills this service | 'category_observed' = bills near-identical services, very likely performs it | 'unconfirmed' = no billing record found. Relay serviceAvailabilityNote and advise confirming; NEVER say they don't offer it (the data misses non-Medicare practices)."},"serviceAvailabilityNote":{"type":["string","null"],"description":"Relay when present."},"telehealthEligible":{"type":"boolean"},"confidence":{"type":"string","description":"high | medium"},"billingOrg":{"type":["string","null"],"description":"Legal entity whose contract the displayed rate belongs to. Often differs from the consumer brand on the door."},"multiEntity":{"type":["boolean","null"],"description":"true = this NPI prices under MULTIPLE contracting entities in this plan and the displayed rate is only the cheapest candidate. Use network-status on this provider to see all candidates before quoting a price."},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchor":{"type":["object","null"],"description":"Medicare reference point. source 'observed' = what Medicare actually paid THIS provider; 'schedule' = Medicare's published fee-schedule rate for the provider's AREA (phrase it as the area rate). A reference point, not the patient's price and not a fair-price claim.","properties":{"source":{"type":"string","description":"observed | schedule"},"medicareAllowed":{"type":"number"},"rateRatio":{"type":["number","null"],"description":"Displayed rate divided by the Medicare amount."},"year":{"type":["number","null"]},"setting":{"type":["string","null"]}}}}}}}}},"totalFound":{"type":"number","description":"Eligible in-network providers for this service in the search area. facilities is the nearest subset with usable rates."},"medicare":{"type":"object","description":"Present on Original Medicare responses. The year's Part B deductible, coinsurance, and limiting charge, whether a Medigap supplement was mentioned, and assumed=true when the person said only \"Medicare\" (confirm it is not an Advantage plan; the medicare_type ask says how). Relay the note once.","properties":{"coverage":{"type":"string","description":"original"},"assumed":{"type":"boolean"},"year":{"type":"number"},"partBDeductible":{"type":"number"},"coinsurancePct":{"type":"number"},"limitingChargePct":{"type":"number"},"medigap":{"type":"boolean"},"note":{"type":"string"}}},"rateFetchNote":{"type":"string","description":"Present when the response is bounded: schedules were sampled evenly (rateSampled=true on affected rows) and/or results cover only the nearest subset of a much larger eligible pool. Relay it: the page is the nearest options, not the area's full price picture."},"multiEntityNote":{"type":["string","null"],"description":"Present once when any provider row is multiEntity: the displayed rate is that provider's group-contract rate and billing may route through an affiliated organization at a different rate. Never quote one number for such a row; resolve via check_network_status."},"sortBasis":{"type":"string","description":"The ordering contract: price within evidence tiers (places with observed billing first, each tier cheapest-first). A cheaper unconfirmed option can sit below confirmed performers; say so when relaying order."},"signalDefinitions":{"type":"object","description":"Once-per-response legend explaining each signal type."},"methodology":{"type":"string","description":"Path to the methodology page."},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"dataVintage":{"type":"string"}}}}}},"429":{"description":"Too many requests: the per-IP limit for this route was exceeded (RATE_LIMITED), or the service is busy (BUSY). Wait Retry-After seconds and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Anonymous pricing is paused. Honor Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}}}}}},"/api/pricing.v1/network-status":{"post":{"tags":["Pricing"],"operationId":"checkNetworkStatus","summary":"Is a named provider or facility in-network, and what do they charge for a service","description":"Whether a specific provider or facility is in-network for the plan, and optionally what they charge for a service. Call this FIRST for any named clinic, brand, facility, or provider: the billing-entity fork (same visit, very different rates by contracting entity) only surfaces here. Anonymous limit: 20 requests per minute per IP (name search is the expensive path).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Whether a specific provider or facility is in-network for the plan, and optionally what they charge for a service. Call this FIRST for any named clinic, brand, facility, or provider: the billing-entity fork (same visit, very different rates by contracting entity) only surfaces here.","properties":{"providerName":{"type":"string","description":"Provider or facility name. Consumer brand names work (matched against NPPES doing-business-as records too). City or ZIP helps disambiguate."},"npi":{"type":"string","description":"10-digit NPI if known. Never required."},"code":{"type":"string","description":"Optional. CPT/HCPCS code from the supported catalog. Prices need a code; omit it to receive the catalog as supportedServices in the response (on REST the catalog is also GET /api/pricing.v1/catalog). There is no free-text service input: the caller selects the code, because codes carry patient facts the server cannot infer (screening vs diagnostic intent, age band, new vs established patient, body part, contrast, duration). An unknown code returns 200 with needsMoreInfo plus the full supportedServices catalog. With a code, each match carries its contracted rate under the plan."},"limit":{"type":"number","description":"Max matches (default 50, max 100). Large systems bill under many NPIs whose network status and rates differ; the breadth is the signal."},"latitude":{"type":"number","description":"Preferred when available. Pair with longitude."},"longitude":{"type":"number"},"zip":{"type":"string","description":"5-digit US ZIP when coordinates are unavailable."},"planHints":{"type":"object","description":"Insurance identifiers from the patient. For anonymous calls this is the ONLY plan input: pass at least payerName (see GET /api/pricing.v1/payers for accepted names). employerName / planName upgrade range estimates to the exact plan's rates when they match a published plan; Group # is only matched for Blue Cross Blue Shield of IL/TX/OK/NM/MT (HCSC). Original Medicare needs no other identifier. Set unavailable=true when the patient cannot provide identifiers, which suppresses further asks and keeps range-based estimates.","properties":{"payerName":{"type":"string","description":"Insurer as the patient names it (e.g. \"Anthem\", \"Blue Shield of California\", \"UnitedHealthcare\", \"Cigna\", \"Aetna\", any Blue Cross Blue Shield plan, \"Original Medicare\"). A bare \"Medicare\" is priced as Original Medicare with a medicare_type ask; Medicare Advantage plans (an insurer's name next to Medicare, HMO/PPO, Part C) are declined with the reason."},"employerName":{"type":"string","description":"Employer the insurance is through, as printed on the card or known to the patient."},"planName":{"type":"string","description":"Plan name printed on the insurance card."},"groupNumber":{"type":"string","description":"Group # exactly as printed on the card. Matches the exact plan for HCSC (BCBS IL/TX/OK/NM/MT) members; other payers do not publish it."},"unavailable":{"type":"boolean","description":"true when the patient cannot provide plan identifiers. Stops plan asks; estimates stay range-based."}}},"patientId":{"type":"string","description":"Family-member patient id on the caller's account. Authenticated calls only: anonymous calls that pass it receive a needsMoreInfo 'auth' ask."}},"required":[]},"example":{"providerName":"One Medical","zip":"94107","code":"99213","planHints":{"payerName":"Anthem"}}}}},"responses":{"200":{"description":"Matches with network status, rates, and billing-entity candidates.","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"supportedServices":{"type":"array","description":"Full pricing catalog, returned when the service could not be resolved. Pick the right code and re-call.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}}}},"location":{"type":"object","description":"Whether the ZIP/coordinates passed were consumed. Only re-ask the patient for location when applied=false.","properties":{"applied":{"type":"boolean"},"source":{"type":["string","null"]}}},"matches":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"],"description":"Legal billing name; null when the index carries no name for the NPI (refer to it by NPI)."},"entityType":{"type":"string","description":"organization | individual"},"otherNames":{"type":["array","null"],"items":{"type":"string"},"description":"NPPES doing-business-as names (consumer brands, e.g. 'One Medical')."},"employers":{"type":["array","null"],"description":"CMS-enrolled group affiliations (the groups this clinician reassigns billing to).","items":{"type":"object","properties":{"organization":{"type":["string","null"]},"npi":{"type":["number","string","null"]},"address":{"type":["string","null"]},"telehealth":{"type":["string","boolean","null"]}}}},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"locationPrecision":{"type":["string","null"],"description":"'address' | 'zip_centroid'"},"distanceKm":{"type":["number","null"],"description":"Approximate km from the given location; present only when one was given. Far same-name organizations stay in the list for breadth, so check it before calling a match local."},"facilityType":{"type":["string","null"],"description":"What kind of entity this NPI is, from its NPPES taxonomy (grouping / classification / specialization). Dozens of NPIs can share one legal name (a hospital, its FQHC subpart, student health, a clinic pharmacy); this tells them apart. Relay it when the name is shared."},"specialtyFit":{"type":["string","null"],"description":"How the entity's registered NPPES specialty fits the requested service: 'expected' = a discipline that delivers it; 'unusual' = a different discipline, or a pediatric/student-health entity priced for a non-pediatric service (relay specialtyFitNote). Absent = no basis for a verdict (generic hospital/clinic entity, no taxonomy, or a category any clinician bills). A label and a within-tier sort key, never a filter: the rate is real contract data."},"specialtyFitNote":{"type":["string","null"],"description":"Present with specialtyFit=unusual: what to confirm before relying on the rate."},"taxonomy":{"type":["string","null"],"description":"NPPES primary taxonomy code."},"taxonomyDescription":{"type":["string","null"]},"subpart":{"type":["boolean","null"],"description":"true = an NPPES organization subpart of parentOrganization (a site, department, or service line), not the system itself."},"parentOrganization":{"type":["string","null"],"description":"NPPES parent organization for subparts."},"mailingState":{"type":["string","null"],"description":"Present only when the NPI's mailing (billing office) state differs from its practice state — an HQ or billing-office record rather than a clinic."},"deactivated":{"type":["string","null"],"description":"NPPES deactivation date when the NPI is deactivated. Do not send anyone there."},"identityNote":{"type":["string","null"],"description":"Present when this legal name covers several billing entities of DIFFERENT kinds in the results. Says which kind and address this one is. Confirm it is the place the patient means before relying on its rate."},"attributionNote":{"type":["string","null"],"description":"Present only on providers whose index entry predates NPI-grain billing attribution: candidates may include unrelated practices that merely share a roster group. Treat evidence-less extra candidates as noise."},"identityCaution":{"type":["string","null"],"description":"A same-name person far from the given location. Verify it is the intended provider before relaying anything."},"inNetwork":{"type":"boolean","description":"true = appears WITH negotiated rates in the plan's published network files. false = not found in the published files; read note for how strong that signal is. Never state a hard 'out of network'."},"networkEvidence":{"type":"number","description":"How many of the plan's network memberships back the in-network claim. 1-2 = thin, 10+ = broad participation."},"note":{"type":"string"},"matchNote":{"type":["string","null"],"description":"Present on matches appended by re-searching the name WITHIN the plan's files (fires when the regular name matches are all outside the plan). Often the system's main billing entity at another location; verify identity before relying on it."},"rate":{"type":["number","null"],"description":"Exact-plan negotiated rate for the requested service; null on fallback matches. On Original Medicare, the approved amount."},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateSampled":{"type":["boolean","null"]},"rateNote":{"type":["string","null"],"description":"In-network but the plan's published files carry no rate for this code. Relay; do not read a missing rate as 'not covered'. On Original Medicare it carries the facility-setting caveat or the code's medicareNote."},"rangeNote":{"type":["string","null"],"description":"Present when rateRange spans 3x or more. Relay it: lead with the median or typicalRate, never the minimum."},"patientShare":{"type":["object","null"],"description":"Original Medicare only: what the person owes for this service at the approved amount. afterDeductible is the coinsurance once the year's Part B deductible is met; beforeDeductibleMet is the most they owe if it is not; limitingChargeMax is set only for non-participating providers (the approved amount plus 15%). 0 on screening benefits and clinical lab tests. Relay the note.","properties":{"afterDeductible":{"type":"number"},"beforeDeductibleMet":{"type":"number"},"limitingChargeMax":{"type":["number","null"]},"note":{"type":"string"}}},"medicareStatus":{"type":["object","null"],"description":"Original Medicare only: how the network answer was derived. basis 'cms_enrollment' (the CMS clinician file; assignment 'participating' = accepts the approved amount as payment in full, 'non_participating' = may bill up to 15% more, null = not recorded) | 'observed_billing' (bills Medicare per public claims, assignment unknown) | 'opt_out' (Medicare pays nothing; private contract) | 'no_record' (not a verdict). Relay the accompanying note.","properties":{"enrolled":{"type":["boolean","null"]},"assignment":{"type":["string","null"],"description":"participating | non_participating | null"},"optedOut":{"type":"boolean"},"basis":{"type":"string","description":"cms_enrollment | observed_billing | opt_out | no_record"}}},"setting":{"type":["string","null"],"description":"office | facility; null when no usable published rate backs the match."},"typicalRate":{"type":["number","null"]},"rateAssessment":{"type":["string","null"],"description":"Set when the rate is far from typical. ALWAYS relay; flags invisible markups like hospital-contract billing of routine visits."},"serviceEvidence":{"type":["string","null"],"description":"Observed-billing evidence from public Medicare claims data: 'observed' = this NPI actually bills this service | 'category_observed' = bills near-identical services, very likely performs it | 'unconfirmed' = no billing record found. Relay serviceAvailabilityNote and advise confirming; NEVER say they don't offer it (the data misses non-Medicare practices)."},"serviceAvailabilityNote":{"type":["string","null"],"description":"Relay when present."},"billingOrg":{"type":["string","null"]},"multiEntity":{"type":["boolean","null"]},"billingOutlook":{"type":["object","null"],"description":"Read this FIRST on a rated match. mode 'single' (one entity, quote it), 'resolved' / 'likely' (a leading entity with its evidence basis: lead with it, mention alternatives), or 'partitioned' (the price is a decision tree on WHO BILLS: relay the 'ask' in patient-answerable terms, walk the branch their answer selects, and NEVER quote one number while partitioned). A 'warning' is binding: a brand-name match does not establish the biller.","properties":{"mode":{"type":"string","description":"single | resolved | likely | partitioned"},"ask":{"type":["string","null"],"description":"What resolves the fork: whose name (billing provider, NPI, or Tax ID) is on a past EOB or bill from this practice. Booking location or brand alone does not decide it, except where the brand's own disclosure is office-scoped (then the ask says which office)."},"warning":{"type":["string","null"]},"partnership":{"type":["string","null"],"description":"The brand's own disclosure of which entity bills, when known."},"leading":{"type":["string","null"],"description":"Legal name of the leading billing entity (modes single/resolved/likely); null while partitioned."},"rate":{"anyOf":[{"type":"number"},{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},{"type":"null"}],"description":"The leading entity's rate or range."},"basis":{"type":["string","null"]},"caution":{"type":["string","null"]},"nominated":{"type":["array","null"],"items":{"type":"object","properties":{"entity":{"type":"string"},"basis":{"type":"string"}}},"description":"Partitioned only: candidate entities with the evidence type(s) nominating each."},"brandLeadSuppressed":{"type":["object","null"],"properties":{"entity":{"type":"string"},"reason":{"type":"string"}}}}},"billingCandidates":{"type":["array","null"],"description":"The rate for this clinician grouped by CONTRACTING ENTITY (billing org TIN), cheapest first. Candidates come from the entities on THIS provider's own roster rows in the payer's files, plus entities linked by CMS enrollment, the payer's directory, the brand's own disclosure, or observed claims; never from merely sharing a network roster group. More than one candidate means the same visit prices differently depending on which legal entity bills it. The files cannot say which entity a given booking will bill: surface the fork and resolve the entity from the name, NPI, or Tax ID on a past EOB or bill before quoting one number.","items":{"type":"object","properties":{"billingOrg":{"type":["string","null"],"description":"Legal/business name of the contracting entity, from the payer's files."},"tin":{"type":["string","null"],"description":"The entity's tax id (billing org identity)."},"rate":{"type":["number","null"]},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateNote":{"type":["string","null"],"description":"Why a range is shown instead of a rate."},"setting":{"type":["string","null"],"description":"office | facility; null when the candidate has no usable published rows."},"nMemberships":{"type":"number","description":"How many of the plan's network files price this NPI under this entity."},"typicalRate":{"type":["number","null"]},"rateAssessment":{"type":["string","null"],"description":"Always relay when present."},"evidence":{"type":"array","items":{"type":"object"},"description":"Evidence tags: observed (real adjudicated claims from linked patients; carries n and last date; the only tag that RESOLVES the fork) | payer_credentialed (the payer's own directory, with an as-of date; nominates, never settles) | brand_disclosed | employer | brand_registration."}}}},"billingCandidatesOmitted":{"type":["number","null"],"description":"The candidate list was capped; this many more contracting entities exist."},"billingNote":{"type":["string","null"],"description":"Present when billingCandidates has multiple entities. Relay it; do NOT quote a single rate without resolving the entity."},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchor":{"type":["object","null"],"description":"Medicare reference point. source 'observed' = what Medicare actually paid THIS provider; 'schedule' = Medicare's published fee-schedule rate for the provider's AREA (phrase it as the area rate). A reference point, not the patient's price and not a fair-price claim.","properties":{"source":{"type":"string","description":"observed | schedule"},"medicareAllowed":{"type":"number"},"rateRatio":{"type":["number","null"],"description":"Displayed rate divided by the Medicare amount."},"year":{"type":["number","null"]},"setting":{"type":["string","null"]}}}}}},"organizations":{"type":["array","null"],"description":"Present when several organization matches share a parent organization or legal name. One entry per system with its billing entities grouped and typed, so a large system reads as a tree (hospital, subparts, clinics) rather than a flat list of same-name rows. Entities list nearest first when a location was given (nearestKm on the system, distanceKm per entity); a system's far-away sites are in the tree for breadth, not as the answer to a local question. Present the system, then the entity the patient means.","items":{"type":"object","properties":{"organization":{"type":"string"},"entities":{"type":"number","description":"Billing NPIs matched under this organization."},"inNetwork":{"type":"number","description":"How many of them are in the plan's files."},"nearestKm":{"type":["number","null"],"description":"Distance to the system's nearest matched entity, when a location was given."},"facilityTypes":{"type":"object","description":"facilityType -> count."},"npis":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"number"},"facilityType":{"type":["string","null"]},"city":{"type":["string","null"]},"distanceKm":{"type":["number","null"],"description":"Approximate km from the given location; entries are listed nearest first."},"inNetwork":{"type":"boolean"},"rate":{"type":["number","null"]},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}}}}}}}},"plan":{"type":"object","description":"What the estimate is based on. Always read matchTier and basis before relaying numbers.","properties":{"payer":{"type":["string","null"],"description":"Payer key (anthem | blueshield_ca | uhc | cigna | aetna | hcsc | medicare). null when no supported insurer could be identified (matchTier no_payer), including Medicare Advantage plans: read needsMoreInfo for what to tell the patient."},"payerLabel":{"type":["string","null"],"description":"Display name for the payer."},"matchTier":{"type":"string","description":"ein_exact | employer_exact | plan_name_exact | group_exact (the exact plan was found: rate is its negotiated rate) | payer_fallback_unbacked (the exact plan was found, but Arlo does not have that plan's own rate files yet: ranges only, and asking for more identifiers will not help) | payer_fallback (insurer known, plan not identified: ranges across the insurer's plans) | medicare_schedule (Original Medicare: rate is Medicare's approved amount for the provider's locality, and the top-level medicare block plus per-provider patientShare say what the person owes) | no_payer (no supported insurer)"},"basis":{"type":"string","description":"Human-readable explanation of what the estimate is based on. Relay it."},"sponsor":{"type":["string","null"],"description":"Matched plan's identity string. May carry the plan-type token (HMO vs PPO) on group-keyed plans; plan type routinely flips the same hospital between in- and out-of-network, so relay it."},"planTypeNote":{"type":["string","null"],"description":"Present when sponsor carries a plan-type token (HMO, PPO, EPO, POS). Relay it: plan type decides network status."},"payerSource":{"type":"string","description":"'hint' (planHints.payerName) or 'linked_coverage' (the authenticated patient's linked insurance records)."},"coverageSelection":{"type":"object","description":"Authenticated calls only. Present when linked records carry more than one active coverage row: {payor, activeRows}. Relay which coverage was used; pass planHints.payerName to pin a different one."},"coverageNote":{"type":"string","description":"Present when Arlo is missing part of the matched plan's network files. Relay it: providers reachable only through those networks may be absent, and 'not found' is a weaker out-of-network signal."},"planHintsReceived":{"type":"object","description":"Present when planHints were passed: {matched, matchedOn?, reason?}. matched=true only when one of the caller's hints selected the plan; matched=false means do not re-ask the patient for the same value."}}},"medicare":{"type":"object","description":"Present on Original Medicare responses. The year's Part B deductible, coinsurance, and limiting charge, whether a Medigap supplement was mentioned, and assumed=true when the person said only \"Medicare\" (confirm it is not an Advantage plan; the medicare_type ask says how). Relay the note once.","properties":{"coverage":{"type":"string","description":"original"},"assumed":{"type":"boolean"},"year":{"type":"number"},"partBDeductible":{"type":"number"},"coinsurancePct":{"type":"number"},"limitingChargePct":{"type":"number"},"medigap":{"type":"boolean"},"note":{"type":"string"}}},"rateFetchNote":{"type":"string"},"networkNote":{"type":["string","null"],"description":"Present when every match is outside the plan. Explains why that is not an out-of-network verdict and how to resolve the real billing entity. Relay it before any network verdict."},"billingEvidenceDefinitions":{"type":"object","description":"Once-per-response legend for billingCandidates[].evidence[].type. Present when any match carries billingCandidates."},"evidenceCardEligible":{"type":"boolean","description":"true when exactly one match carries evidence signals (a UI may render an evidence card)."},"signalDefinitions":{"type":"object"},"methodology":{"type":"string"},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."}}}}},"headers":{"X-Arlo-Api-Version":{"schema":{"type":"string"},"description":"Contract version (currently 1)."},"Link":{"schema":{"type":"string"},"description":"rel=\"service-doc\" points at guide.md, rel=\"service-desc\" at openapi.json."}}},"429":{"description":"Too many requests: the per-IP limit for this route was exceeded (RATE_LIMITED), or the service is busy (BUSY). Wait Retry-After seconds and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Anonymous pricing is paused. Honor Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}}}}},"get":{"tags":["Pricing"],"operationId":"checkNetworkStatusGet","summary":"Same as POST with flat query parameters","parameters":[{"name":"providerName","in":"query","schema":{"type":"string"}},{"name":"npi","in":"query","schema":{"type":"string"}},{"name":"code","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"zip","in":"query","schema":{"type":"string"},"description":"5-digit US ZIP"},{"name":"latitude","in":"query","schema":{"type":"number"}},{"name":"longitude","in":"query","schema":{"type":"number"}},{"name":"payerName","in":"query","schema":{"type":"string"},"description":"planHints.payerName"},{"name":"employerName","in":"query","schema":{"type":"string"},"description":"planHints.employerName"},{"name":"planName","in":"query","schema":{"type":"string"},"description":"planHints.planName"},{"name":"groupNumber","in":"query","schema":{"type":"string"},"description":"planHints.groupNumber (HCSC members only)"},{"name":"planUnavailable","in":"query","schema":{"type":"boolean"},"description":"planHints.unavailable"}],"responses":{"200":{"description":"Matches","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"supportedServices":{"type":"array","description":"Full pricing catalog, returned when the service could not be resolved. Pick the right code and re-call.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"}}}},"location":{"type":"object","description":"Whether the ZIP/coordinates passed were consumed. Only re-ask the patient for location when applied=false.","properties":{"applied":{"type":"boolean"},"source":{"type":["string","null"]}}},"matches":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"],"description":"Legal billing name; null when the index carries no name for the NPI (refer to it by NPI)."},"entityType":{"type":"string","description":"organization | individual"},"otherNames":{"type":["array","null"],"items":{"type":"string"},"description":"NPPES doing-business-as names (consumer brands, e.g. 'One Medical')."},"employers":{"type":["array","null"],"description":"CMS-enrolled group affiliations (the groups this clinician reassigns billing to).","items":{"type":"object","properties":{"organization":{"type":["string","null"]},"npi":{"type":["number","string","null"]},"address":{"type":["string","null"]},"telehealth":{"type":["string","boolean","null"]}}}},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"locationPrecision":{"type":["string","null"],"description":"'address' | 'zip_centroid'"},"distanceKm":{"type":["number","null"],"description":"Approximate km from the given location; present only when one was given. Far same-name organizations stay in the list for breadth, so check it before calling a match local."},"facilityType":{"type":["string","null"],"description":"What kind of entity this NPI is, from its NPPES taxonomy (grouping / classification / specialization). Dozens of NPIs can share one legal name (a hospital, its FQHC subpart, student health, a clinic pharmacy); this tells them apart. Relay it when the name is shared."},"specialtyFit":{"type":["string","null"],"description":"How the entity's registered NPPES specialty fits the requested service: 'expected' = a discipline that delivers it; 'unusual' = a different discipline, or a pediatric/student-health entity priced for a non-pediatric service (relay specialtyFitNote). Absent = no basis for a verdict (generic hospital/clinic entity, no taxonomy, or a category any clinician bills). A label and a within-tier sort key, never a filter: the rate is real contract data."},"specialtyFitNote":{"type":["string","null"],"description":"Present with specialtyFit=unusual: what to confirm before relying on the rate."},"taxonomy":{"type":["string","null"],"description":"NPPES primary taxonomy code."},"taxonomyDescription":{"type":["string","null"]},"subpart":{"type":["boolean","null"],"description":"true = an NPPES organization subpart of parentOrganization (a site, department, or service line), not the system itself."},"parentOrganization":{"type":["string","null"],"description":"NPPES parent organization for subparts."},"mailingState":{"type":["string","null"],"description":"Present only when the NPI's mailing (billing office) state differs from its practice state — an HQ or billing-office record rather than a clinic."},"deactivated":{"type":["string","null"],"description":"NPPES deactivation date when the NPI is deactivated. Do not send anyone there."},"identityNote":{"type":["string","null"],"description":"Present when this legal name covers several billing entities of DIFFERENT kinds in the results. Says which kind and address this one is. Confirm it is the place the patient means before relying on its rate."},"attributionNote":{"type":["string","null"],"description":"Present only on providers whose index entry predates NPI-grain billing attribution: candidates may include unrelated practices that merely share a roster group. Treat evidence-less extra candidates as noise."},"identityCaution":{"type":["string","null"],"description":"A same-name person far from the given location. Verify it is the intended provider before relaying anything."},"inNetwork":{"type":"boolean","description":"true = appears WITH negotiated rates in the plan's published network files. false = not found in the published files; read note for how strong that signal is. Never state a hard 'out of network'."},"networkEvidence":{"type":"number","description":"How many of the plan's network memberships back the in-network claim. 1-2 = thin, 10+ = broad participation."},"note":{"type":"string"},"matchNote":{"type":["string","null"],"description":"Present on matches appended by re-searching the name WITHIN the plan's files (fires when the regular name matches are all outside the plan). Often the system's main billing entity at another location; verify identity before relying on it."},"rate":{"type":["number","null"],"description":"Exact-plan negotiated rate for the requested service; null on fallback matches. On Original Medicare, the approved amount."},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateSampled":{"type":["boolean","null"]},"rateNote":{"type":["string","null"],"description":"In-network but the plan's published files carry no rate for this code. Relay; do not read a missing rate as 'not covered'. On Original Medicare it carries the facility-setting caveat or the code's medicareNote."},"rangeNote":{"type":["string","null"],"description":"Present when rateRange spans 3x or more. Relay it: lead with the median or typicalRate, never the minimum."},"patientShare":{"type":["object","null"],"description":"Original Medicare only: what the person owes for this service at the approved amount. afterDeductible is the coinsurance once the year's Part B deductible is met; beforeDeductibleMet is the most they owe if it is not; limitingChargeMax is set only for non-participating providers (the approved amount plus 15%). 0 on screening benefits and clinical lab tests. Relay the note.","properties":{"afterDeductible":{"type":"number"},"beforeDeductibleMet":{"type":"number"},"limitingChargeMax":{"type":["number","null"]},"note":{"type":"string"}}},"medicareStatus":{"type":["object","null"],"description":"Original Medicare only: how the network answer was derived. basis 'cms_enrollment' (the CMS clinician file; assignment 'participating' = accepts the approved amount as payment in full, 'non_participating' = may bill up to 15% more, null = not recorded) | 'observed_billing' (bills Medicare per public claims, assignment unknown) | 'opt_out' (Medicare pays nothing; private contract) | 'no_record' (not a verdict). Relay the accompanying note.","properties":{"enrolled":{"type":["boolean","null"]},"assignment":{"type":["string","null"],"description":"participating | non_participating | null"},"optedOut":{"type":"boolean"},"basis":{"type":"string","description":"cms_enrollment | observed_billing | opt_out | no_record"}}},"setting":{"type":["string","null"],"description":"office | facility; null when no usable published rate backs the match."},"typicalRate":{"type":["number","null"]},"rateAssessment":{"type":["string","null"],"description":"Set when the rate is far from typical. ALWAYS relay; flags invisible markups like hospital-contract billing of routine visits."},"serviceEvidence":{"type":["string","null"],"description":"Observed-billing evidence from public Medicare claims data: 'observed' = this NPI actually bills this service | 'category_observed' = bills near-identical services, very likely performs it | 'unconfirmed' = no billing record found. Relay serviceAvailabilityNote and advise confirming; NEVER say they don't offer it (the data misses non-Medicare practices)."},"serviceAvailabilityNote":{"type":["string","null"],"description":"Relay when present."},"billingOrg":{"type":["string","null"]},"multiEntity":{"type":["boolean","null"]},"billingOutlook":{"type":["object","null"],"description":"Read this FIRST on a rated match. mode 'single' (one entity, quote it), 'resolved' / 'likely' (a leading entity with its evidence basis: lead with it, mention alternatives), or 'partitioned' (the price is a decision tree on WHO BILLS: relay the 'ask' in patient-answerable terms, walk the branch their answer selects, and NEVER quote one number while partitioned). A 'warning' is binding: a brand-name match does not establish the biller.","properties":{"mode":{"type":"string","description":"single | resolved | likely | partitioned"},"ask":{"type":["string","null"],"description":"What resolves the fork: whose name (billing provider, NPI, or Tax ID) is on a past EOB or bill from this practice. Booking location or brand alone does not decide it, except where the brand's own disclosure is office-scoped (then the ask says which office)."},"warning":{"type":["string","null"]},"partnership":{"type":["string","null"],"description":"The brand's own disclosure of which entity bills, when known."},"leading":{"type":["string","null"],"description":"Legal name of the leading billing entity (modes single/resolved/likely); null while partitioned."},"rate":{"anyOf":[{"type":"number"},{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},{"type":"null"}],"description":"The leading entity's rate or range."},"basis":{"type":["string","null"]},"caution":{"type":["string","null"]},"nominated":{"type":["array","null"],"items":{"type":"object","properties":{"entity":{"type":"string"},"basis":{"type":"string"}}},"description":"Partitioned only: candidate entities with the evidence type(s) nominating each."},"brandLeadSuppressed":{"type":["object","null"],"properties":{"entity":{"type":"string"},"reason":{"type":"string"}}}}},"billingCandidates":{"type":["array","null"],"description":"The rate for this clinician grouped by CONTRACTING ENTITY (billing org TIN), cheapest first. Candidates come from the entities on THIS provider's own roster rows in the payer's files, plus entities linked by CMS enrollment, the payer's directory, the brand's own disclosure, or observed claims; never from merely sharing a network roster group. More than one candidate means the same visit prices differently depending on which legal entity bills it. The files cannot say which entity a given booking will bill: surface the fork and resolve the entity from the name, NPI, or Tax ID on a past EOB or bill before quoting one number.","items":{"type":"object","properties":{"billingOrg":{"type":["string","null"],"description":"Legal/business name of the contracting entity, from the payer's files."},"tin":{"type":["string","null"],"description":"The entity's tax id (billing org identity)."},"rate":{"type":["number","null"]},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}},"rateNote":{"type":["string","null"],"description":"Why a range is shown instead of a rate."},"setting":{"type":["string","null"],"description":"office | facility; null when the candidate has no usable published rows."},"nMemberships":{"type":"number","description":"How many of the plan's network files price this NPI under this entity."},"typicalRate":{"type":["number","null"]},"rateAssessment":{"type":["string","null"],"description":"Always relay when present."},"evidence":{"type":"array","items":{"type":"object"},"description":"Evidence tags: observed (real adjudicated claims from linked patients; carries n and last date; the only tag that RESOLVES the fork) | payer_credentialed (the payer's own directory, with an as-of date; nominates, never settles) | brand_disclosed | employer | brand_registration."}}}},"billingCandidatesOmitted":{"type":["number","null"],"description":"The candidate list was capped; this many more contracting entities exist."},"billingNote":{"type":["string","null"],"description":"Present when billingCandidates has multiple entities. Relay it; do NOT quote a single rate without resolving the entity."},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchor":{"type":["object","null"],"description":"Medicare reference point. source 'observed' = what Medicare actually paid THIS provider; 'schedule' = Medicare's published fee-schedule rate for the provider's AREA (phrase it as the area rate). A reference point, not the patient's price and not a fair-price claim.","properties":{"source":{"type":"string","description":"observed | schedule"},"medicareAllowed":{"type":"number"},"rateRatio":{"type":["number","null"],"description":"Displayed rate divided by the Medicare amount."},"year":{"type":["number","null"]},"setting":{"type":["string","null"]}}}}}},"organizations":{"type":["array","null"],"description":"Present when several organization matches share a parent organization or legal name. One entry per system with its billing entities grouped and typed, so a large system reads as a tree (hospital, subparts, clinics) rather than a flat list of same-name rows. Entities list nearest first when a location was given (nearestKm on the system, distanceKm per entity); a system's far-away sites are in the tree for breadth, not as the answer to a local question. Present the system, then the entity the patient means.","items":{"type":"object","properties":{"organization":{"type":"string"},"entities":{"type":"number","description":"Billing NPIs matched under this organization."},"inNetwork":{"type":"number","description":"How many of them are in the plan's files."},"nearestKm":{"type":["number","null"],"description":"Distance to the system's nearest matched entity, when a location was given."},"facilityTypes":{"type":"object","description":"facilityType -> count."},"npis":{"type":"array","items":{"type":"object","properties":{"npi":{"type":"number"},"facilityType":{"type":["string","null"]},"city":{"type":["string","null"]},"distanceKm":{"type":["number","null"],"description":"Approximate km from the given location; entries are listed nearest first."},"inNetwork":{"type":"boolean"},"rate":{"type":["number","null"]},"rateRange":{"type":["object","null"],"description":"Spread across the payer's plan schedules when the exact plan is not matched. When wide (see note), median and typicalRate are the useful reference points.","properties":{"min":{"type":"number"},"max":{"type":"number"},"median":{"type":"number"}}}}}}}}},"plan":{"type":"object","description":"What the estimate is based on. Always read matchTier and basis before relaying numbers.","properties":{"payer":{"type":["string","null"],"description":"Payer key (anthem | blueshield_ca | uhc | cigna | aetna | hcsc | medicare). null when no supported insurer could be identified (matchTier no_payer), including Medicare Advantage plans: read needsMoreInfo for what to tell the patient."},"payerLabel":{"type":["string","null"],"description":"Display name for the payer."},"matchTier":{"type":"string","description":"ein_exact | employer_exact | plan_name_exact | group_exact (the exact plan was found: rate is its negotiated rate) | payer_fallback_unbacked (the exact plan was found, but Arlo does not have that plan's own rate files yet: ranges only, and asking for more identifiers will not help) | payer_fallback (insurer known, plan not identified: ranges across the insurer's plans) | medicare_schedule (Original Medicare: rate is Medicare's approved amount for the provider's locality, and the top-level medicare block plus per-provider patientShare say what the person owes) | no_payer (no supported insurer)"},"basis":{"type":"string","description":"Human-readable explanation of what the estimate is based on. Relay it."},"sponsor":{"type":["string","null"],"description":"Matched plan's identity string. May carry the plan-type token (HMO vs PPO) on group-keyed plans; plan type routinely flips the same hospital between in- and out-of-network, so relay it."},"planTypeNote":{"type":["string","null"],"description":"Present when sponsor carries a plan-type token (HMO, PPO, EPO, POS). Relay it: plan type decides network status."},"payerSource":{"type":"string","description":"'hint' (planHints.payerName) or 'linked_coverage' (the authenticated patient's linked insurance records)."},"coverageSelection":{"type":"object","description":"Authenticated calls only. Present when linked records carry more than one active coverage row: {payor, activeRows}. Relay which coverage was used; pass planHints.payerName to pin a different one."},"coverageNote":{"type":"string","description":"Present when Arlo is missing part of the matched plan's network files. Relay it: providers reachable only through those networks may be absent, and 'not found' is a weaker out-of-network signal."},"planHintsReceived":{"type":"object","description":"Present when planHints were passed: {matched, matchedOn?, reason?}. matched=true only when one of the caller's hints selected the plan; matched=false means do not re-ask the patient for the same value."}}},"medicare":{"type":"object","description":"Present on Original Medicare responses. The year's Part B deductible, coinsurance, and limiting charge, whether a Medigap supplement was mentioned, and assumed=true when the person said only \"Medicare\" (confirm it is not an Advantage plan; the medicare_type ask says how). Relay the note once.","properties":{"coverage":{"type":"string","description":"original"},"assumed":{"type":"boolean"},"year":{"type":"number"},"partBDeductible":{"type":"number"},"coinsurancePct":{"type":"number"},"limitingChargePct":{"type":"number"},"medigap":{"type":"boolean"},"note":{"type":"string"}}},"rateFetchNote":{"type":"string"},"networkNote":{"type":["string","null"],"description":"Present when every match is outside the plan. Explains why that is not an out-of-network verdict and how to resolve the real billing entity. Relay it before any network verdict."},"billingEvidenceDefinitions":{"type":"object","description":"Once-per-response legend for billingCandidates[].evidence[].type. Present when any match carries billingCandidates."},"evidenceCardEligible":{"type":"boolean","description":"true when exactly one match carries evidence signals (a UI may render an evidence card)."},"signalDefinitions":{"type":"object"},"methodology":{"type":"string"},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."}}}}}},"429":{"description":"Too many requests: the per-IP limit for this route was exceeded (RATE_LIMITED), or the service is busy (BUSY). Wait Retry-After seconds and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Anonymous pricing is paused. Honor Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}}}}}},"/api/pricing.v1/provider-evidence":{"post":{"tags":["Pricing"],"operationId":"getProviderEvidence","summary":"Public-data evidence about one provider (by NPI)","description":"Public-data evidence about ONE specific provider: Medicare-derived experience, facility outcome context (facility-level, never the clinician's own outcome), Medicare payment anchors, or an explained absence. Use only once the conversation is focused on one provider. Anonymous limit: 60 requests per minute per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Public-data evidence about ONE specific provider: Medicare-derived experience, facility outcome context (facility-level, never the clinician's own outcome), Medicare payment anchors, or an explained absence. Use only once the conversation is focused on one provider.","properties":{"npi":{"type":"string","description":"The provider's 10-digit NPI. Resolve it first via network-status (name search) or from search results."},"code":{"type":"string","description":"Optional catalog code to scope evidence to one service."}},"required":["npi"]},"example":{"npi":"1003041625","code":"45378"}}}},"responses":{"200":{"description":"Evidence card payload","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"]},"entityType":{"type":"string","description":"organization | individual"},"city":{"type":["string","null"]},"state":{"type":["string","null"]}},"required":["npi"]},"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchors":{"type":"array","description":"What Medicare actually paid this provider per service. Reference points from public data, not fair-price claims and not the patient's price.","items":{"type":"object","properties":{"code":{"type":"string"},"setting":{"type":"string","description":"facility | office"},"service":{"type":["string","null"]},"medicareAllowed":{"type":"number"},"year":{"type":"number"}},"required":["code","medicareAllowed","year"]}},"signalDefinitions":{"type":"object"},"methodology":{"type":"string"},"corrections":{"type":"string"},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}}}}}},"headers":{"X-Arlo-Api-Version":{"schema":{"type":"string"},"description":"Contract version (currently 1)."},"Link":{"schema":{"type":"string"},"description":"rel=\"service-doc\" points at guide.md, rel=\"service-desc\" at openapi.json."}}},"429":{"description":"Too many requests: the per-IP limit for this route was exceeded (RATE_LIMITED), or the service is busy (BUSY). Wait Retry-After seconds and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Anonymous pricing is paused. Honor Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}}}}},"get":{"tags":["Pricing"],"operationId":"getProviderEvidenceGet","summary":"Same as POST with query parameters","parameters":[{"name":"npi","in":"query","required":true,"schema":{"type":"string"}},{"name":"code","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Evidence card payload","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"object","properties":{"npi":{"type":"number"},"name":{"type":["string","null"]},"entityType":{"type":"string","description":"organization | individual"},"city":{"type":["string","null"]},"state":{"type":["string","null"]}},"required":["npi"]},"service":{"type":"object","description":"Echo of the resolved service. VERIFY appliesTo against the actual patient before relaying any number.","properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"appliesTo":{"type":"string","description":"The selection fact baked into this code (age band, new vs established, screening vs diagnostic, contrast, duration)."},"priceNote":{"type":["string","null"],"description":"Pricing semantics that change what the number means (per-unit billing, ACA preventive $0 cost-share, facility fee excludes the physician's separate bill). Relay whenever present."},"medicareNote":{"type":["string","null"],"description":"Original Medicare responses only, on codes Medicare does not pay under this code (routine physicals, telemedicine-specific codes, anesthesia, contraceptive IUD): what Medicare covers instead and which code to use. Relay it and switch codes when it names one."},"relatedCodes":{"type":"array","description":"Sibling codes selected by a different patient fact (age band, complexity, screening vs diagnostic). If one fits the patient better, re-call with it.","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":["string","null"]},"when":{"type":"string","description":"The patient fact that selects this sibling."}}}}}},"signals":{"type":"array","description":"Pre-gated evidence signals from public CMS data. Relay each signal's 'display' sentence as written; never compress into ranking or 'best doctor' language; never treat absence as negative (non-Medicare practices legitimately lack data). An 'exclusion' signal (federal OIG exclusion list) is a legal-status safety notice: always relay it plainly.","items":{"type":"object","properties":{"type":{"type":"string","description":"volume | outcome_context | optout | absence | exclusion"},"hcpcs":{"type":"string"},"floor":{"type":"number","description":"Volume floor: performed at least this many per year (Medicare)."},"pctl":{"type":"number","description":"National percentile. Present only when high (positives-only display)."},"level":{"type":"string","description":"'facility' signals describe the facility, never the clinician."},"facility":{"type":"string"},"measure":{"type":"string"},"score":{"type":["number","null"]},"ci":{"type":"array","items":{"type":["number","null"]}},"verdict":{"type":["string","null"]},"denominator":{"type":["number","null"]},"display":{"type":"string","description":"Derivation sentence. Relay verbatim or summarize without changing meaning."}},"required":["type","display"]}},"medicareAnchors":{"type":"array","description":"What Medicare actually paid this provider per service. Reference points from public data, not fair-price claims and not the patient's price.","items":{"type":"object","properties":{"code":{"type":"string"},"setting":{"type":"string","description":"facility | office"},"service":{"type":["string","null"]},"medicareAllowed":{"type":"number"},"year":{"type":"number"}},"required":["code","medicareAllowed","year"]}},"signalDefinitions":{"type":"object"},"methodology":{"type":"string"},"corrections":{"type":"string"},"disclaimer":{"type":"string","description":"ALWAYS convey to the patient: estimates come from the insurer's published data and are not a price guarantee."},"needsMoreInfo":{"type":"array","description":"Asks to relay to the patient. Answering them improves the estimate (ranges become the plan's exact rates). Each ask names the field, why it matters, and how to obtain it. A medicare_type ask means the numbers assume Original Medicare and the person must confirm they are not on a Medicare Advantage plan.","items":{"type":"object","properties":{"field":{"type":"string"},"ask":{"type":"string"},"why":{"type":"string"},"how":{"type":"string","description":"How to obtain it: ask the patient, read an EOB, or a public lookup (e.g. NPI registry)."},"options":{"type":"array","items":{"type":"string"}}},"required":["field","ask"]}}}}}}},"429":{"description":"Too many requests: the per-IP limit for this route was exceeded (RATE_LIMITED), or the service is busy (BUSY). Wait Retry-After seconds and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Anonymous pricing is paused. Honor Retry-After.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code: RATE_LIMITED | BUSY | PRICING_PUBLIC_DISABLED | NOT_FOUND | PRICING_SEARCH_FAILED | PRICING_NETWORK_STATUS_FAILED | PROVIDER_EVIDENCE_FAILED"},"message":{"type":"string"},"retryAfterSeconds":{"type":"number"}},"required":["error"]}}}}}}}}}