Loa Healthcare Pricing REST API

{"openapi":"3.1.0","info":{"title":"Loa Healthcare Pricing API","version":"0.1.0","description":"Search source-labeled U.S. healthcare providers and hospitals, compare medical prices, and submit reviewed data updates.","termsOfService":"https://www.loacare.com/terms","contact":{"name":"Loa","url":"https://www.loacare.com/api-partnership"},"license":{"name":"Loa Terms of Service","url":"https://www.loacare.com/terms"}},"externalDocs":{"description":"Loa healthcare pricing API documentation","url":"https://www.loacare.com/api-partnership"},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"ProviderApiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Optional provider API key for metered clients. Local public reads still work without a key."}},"schemas":{"ErrorResponse":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"$ref":"#/components/schemas/NamedError"}}},"NamedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"Pagination":{"type":"object","required":["limit","returned"],"properties":{"limit":{"type":"integer"},"returned":{"type":"integer"}}},"Provenance":{"type":"object","required":["authority","confidence","caveats"],"properties":{"authority":{"type":"string"},"source_type":{"type":"string"},"sourceType":{"type":"string"},"source_label":{"type":"string"},"sourceLabel":{"type":"string"},"sourceUpdatedAt":{"type":"string"},"loaReviewedAt":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]},"caveats":{"type":"array","items":{"type":"string"}}}},"EntitySearchResult":{"type":"object","required":["id","entity_type","slug","canonical_name"],"properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","enum":["hospital","provider"]},"slug":{"type":"string"},"canonical_name":{"type":"string"},"display_name":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip_code":{"type":["string","null"]},"data_quality_score":{"type":["number","null"]},"updated_at":{"type":"string"}}},"EntityProfile":{"type":"object","required":["id","entityType","slug","canonicalName"],"properties":{"id":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["hospital","provider"]},"slug":{"type":"string"},"canonicalName":{"type":"string"},"displayName":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zipCode":{"type":["string","null"]},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"npi":{"type":["string","null"]},"ccn":{"type":["string","null"]},"hpfId":{"type":["string","null"]},"dataQualityScore":{"type":["number","null"]},"updatedAt":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}}},"ProfileFieldProvenance":{"type":"object","required":["authority","source_type","source_label","confidence"],"properties":{"authority":{"type":"string"},"source_type":{"type":"string"},"source_label":{"type":"string"},"confidence":{"type":"string"},"loa_reviewed_at":{"type":["string","null"]}}},"ResolvedEntity":{"type":"object","required":["id","entityType","slug","canonicalName"],"properties":{"id":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["hospital","provider"]},"slug":{"type":"string"},"canonicalName":{"type":"string"},"city":{"type":["string","null"]},"state":{"type":["string","null"]}}},"ComparableResolvedPrice":{"type":"object","required":["entityPageId","cptCode","codeType","priceCents","priceKind","label","provenance"],"properties":{"entityPageId":{"type":"string","format":"uuid"},"cptCode":{"type":"string"},"codeType":{"type":"string"},"procedureDescription":{"type":"string"},"serviceCategory":{"type":"string"},"priceCents":{"type":["integer","null"]},"priceKind":{"type":"string"},"label":{"type":"string"},"payerName":{"type":"string"},"planName":{"type":"string"},"setting":{"type":"string"},"billingClass":{"type":"string"},"component":{"type":"string"},"sourceRowId":{"type":"string"},"basePriceIndexId":{"type":"string"},"overlayRelationship":{"type":"string"},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"ResolvedPrice":{"allOf":[{"$ref":"#/components/schemas/ComparableResolvedPrice"},{"type":"object","properties":{"comparableMrfPrice":{"$ref":"#/components/schemas/ComparableResolvedPrice"}}}]},"EntitySearchResponse":{"type":"object","required":["request_id","results","pagination","provenance"],"properties":{"request_id":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EntitySearchResult"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"EntityProfileResponse":{"type":"object","required":["request_id","entity","provenance","profile_field_provenance"],"properties":{"request_id":{"type":"string"},"entity":{"$ref":"#/components/schemas/EntityProfile"},"provenance":{"$ref":"#/components/schemas/Provenance"},"profile_field_provenance":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ProfileFieldProvenance"}}}},"EntityPricesResponse":{"type":"object","required":["request_id","entity","prices","pagination","provenance"],"properties":{"request_id":{"type":"string"},"entity":{"$ref":"#/components/schemas/ResolvedEntity"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/ResolvedPrice"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"PriceCompareResponse":{"type":"object","required":["request_id","query","comparisons","provenance"],"properties":{"request_id":{"type":"string"},"query":{"type":"object","additionalProperties":true},"comparisons":{"type":"array","items":{"type":"object","additionalProperties":true}},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"EntityUpdatePriceItem":{"type":"object","required":["cpt_code"],"properties":{"cpt_code":{"type":"string","minLength":3,"maxLength":20,"pattern":"^(\\d{5}|[A-Za-z]\\d{4})$","description":"5-digit CPT code or HCPCS Level II code."},"code_type":{"type":"string","default":"CPT"},"service_name":{"type":"string","maxLength":300},"price_kind":{"type":"string","enum":["cash","discounted_cash","package_cash","payer_negotiated"],"default":"cash"},"proposed_price_cents":{"type":"integer","minimum":1},"payer_name":{"type":"string","maxLength":300},"plan_name":{"type":"string","maxLength":300},"setting":{"type":"string","maxLength":100},"billing_class":{"type":"string","maxLength":100},"component":{"type":"string","enum":["global","professional","facility","unknown"],"default":"unknown"},"included_services":{"type":"array","items":{"type":"string","maxLength":300}},"exclusions":{"type":"string","maxLength":1000},"price_notes":{"type":"string","maxLength":1000}}},"EntityUpdateRequest":{"type":"object","required":["submitter_email","request_type"],"properties":{"entity_page_id":{"type":"string","format":"uuid"},"entity_slug":{"type":"string"},"entity_type":{"type":"string","enum":["hospital","provider","unknown"]},"submitter_email":{"type":"string","format":"email"},"submitter_name":{"type":"string"},"submitter_organization":{"type":"string","maxLength":300,"description":"Provider, hospital, or agent organization represented by the submitter."},"submitter_role":{"type":"string"},"submitter_phone":{"type":"string"},"source_urls":{"type":"array","maxItems":10,"items":{"type":"string","format":"uri"},"description":"Public URLs reviewers can use to verify the submitted change."},"source_notes":{"type":"string","maxLength":2000,"description":"Short verification notes, source context, or callback instructions."},"attestation":{"type":"string","enum":["provider_representative","authorized_agent","public_source","other"],"description":"How the submitter is connected to the submitted evidence."},"request_type":{"type":"string","enum":["price_update","profile_correction","new_listing","remove_listing","other"]},"proposed_changes":{"type":"object","additionalProperties":true,"description":"Structured proposed changes. Serialized JSON must be 25 KB or less."},"uploaded_file_url":{"type":"string","format":"uri"},"idempotency_key":{"type":"string","minLength":8,"maxLength":200,"description":"Optional stable retry key. Loa derives one from the payload if omitted."},"price_items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/EntityUpdatePriceItem"}}}},"EntityUpdateResponse":{"type":"object","required":["request_id","update_request_id","status","reused_existing"],"properties":{"request_id":{"type":"string"},"update_request_id":{"type":"string","format":"uuid"},"entity_page_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string"},"reused_existing":{"type":"boolean"}}},"EntityAnalyticsEvent":{"type":"object","required":["entity_page_id","event_type"],"properties":{"entity_page_id":{"type":"string","format":"uuid"},"event_type":{"type":"string","enum":["profile_view","search_impression","profile_click","outbound_click","api_result_shown"]},"source":{"type":"string","maxLength":120},"anonymous_session_id":{"type":"string","maxLength":200},"search_query":{"type":"string","maxLength":500},"searcher_city":{"type":"string","maxLength":120},"searcher_state":{"type":"string","maxLength":60,"description":"Two-letter state code or full state name, normalized before storage."},"metadata":{"type":"object","additionalProperties":true,"description":"Allowlisted analytics context. Identifiers and email-like values are stripped before storage."},"dedupe_key":{"type":"string","maxLength":200}}},"EntityAnalyticsResponse":{"type":"object","required":["request_id","ok"],"properties":{"request_id":{"type":"string"},"ok":{"type":"boolean"}}}}},"paths":{"/entities/search":{"get":{"operationId":"searchEntities","summary":"Search provider and hospital entities","security":[{},{"ProviderApiKey":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["hospital","provider"]}},{"name":"state","in":"query","schema":{"type":"string"},"description":"Two-letter state code or full state name. Unknown states return InvalidEntitySearch."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Entity search results with request_id and pagination.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitySearchResponse"}}}},"400":{"description":"InvalidEntitySearch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"ApiClientUnauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"ApiClientDisabled or ApiClientScopeDenied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"ApiRateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/entities/{slug}":{"get":{"operationId":"getEntity","summary":"Get one entity profile by exact Loa slug or entity_pages.id","security":[{},{"ProviderApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Exact Loa slug, or entity_pages.id for local/API clients."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["hospital","provider"]}}],"responses":{"200":{"description":"Entity profile with provenance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityProfileResponse"}}}},"400":{"description":"InvalidEntityType.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"ApiClientUnauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"ApiClientDisabled or ApiClientScopeDenied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"EntityNotFound.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"ApiRateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/entities/{slug}/prices":{"get":{"operationId":"getEntityPrices","summary":"Get source-labeled prices for one entity by exact Loa slug or entity_pages.id","security":[{},{"ProviderApiKey":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Exact Loa slug, or entity_pages.id for local/API clients."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["hospital","provider"]}},{"name":"cpt_code","in":"query","schema":{"type":"string"},"description":"Optional CPT code filter. Repeat or comma-separate values, max 25 codes."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Resolved prices with provenance and explicit unavailable rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityPricesResponse"}}}},"400":{"description":"InvalidEntityType or InvalidEntityPricesRequest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"ApiClientUnauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"ApiClientDisabled or ApiClientScopeDenied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"EntityNotFound.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"ApiRateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/prices/compare":{"get":{"operationId":"comparePrices","summary":"Compare source-labeled prices across entities","security":[{},{"ProviderApiKey":[]}],"parameters":[{"name":"entity","in":"query","required":true,"schema":{"type":"string"},"description":"One or more Loa entity slugs. Repeat or comma-separate values, max 10 entities."},{"name":"cpt_code","in":"query","required":true,"schema":{"type":"string"},"description":"One or more CPT codes. Repeat or comma-separate values, max 10 codes."},{"name":"limit_per_entity","in":"query","schema":{"type":"integer","minimum":1,"maximum":25}}],"responses":{"200":{"description":"Grouped comparisons by CPT code and entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceCompareResponse"}}}},"400":{"description":"InvalidPriceCompareRequest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"ApiClientUnauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"ApiClientDisabled or ApiClientScopeDenied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"EntityNotFound.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"ApiRateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/entity-updates":{"post":{"operationId":"submitEntityUpdate","summary":"Submit a provider or hospital update request for Loa review","description":"Creates a pending reviewed update request from a public form, API client, or agent. A provider API key is optional; Loa never changes public runtime data until staff approve the request.","security":[{},{"ProviderApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUpdateRequest"}}}},"responses":{"200":{"description":"Existing idempotent request returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUpdateResponse"}}}},"201":{"description":"Update request created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUpdateResponse"}}}},"400":{"description":"UpdateRequestValidationFailed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"ApiClientUnauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"ApiClientDisabled or ApiClientScopeDenied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"EntityNotFound.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"ApiRateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/entity-analytics":{"post":{"operationId":"recordEntityAnalytics","summary":"Record an aggregate-safe entity analytics beacon","description":"Client beacon for SEO/profile traffic, outbound clicks, and search impressions. Raw identifiers are hashed or stripped before storage and provider dashboards only show aggregates.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityAnalyticsEvent"}}}},"responses":{"200":{"description":"Analytics event accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityAnalyticsResponse"}}}},"400":{"description":"InvalidAnalyticsEvent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"AnalyticsRateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"AnalyticsWriteFailed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}