{"openapi":"3.1.0","info":{"title":"TrustedPerch Partner API","version":"1.0.0","summary":"CliniVibes hospital and housing integration","description":"The TrustedPerch Partner API allows CliniVibes to:\n\n- Retrieve hospital information using a CMS Certification Number.\n- Retrieve nearby verified TrustedPerch housing.\n- Submit aggregate hospital review insights.\n\nHousing data is read-only. Hospital insight data is write-only.\n"},"servers":[{"url":"https://trustedperch.com/api/v1/partners","description":"Production"}],"tags":[{"name":"Hospitals"},{"name":"Housing"},{"name":"Hospital Insights"}],"paths":{"/hospitals/{ccn}":{"get":{"tags":["Hospitals"],"summary":"Get hospital information","operationId":"getHospitalByCcn","description":"Returns the TrustedPerch hospital record associated with a\nsix-digit CMS Certification Number.\n","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/Ccn"}],"responses":{"200":{"description":"Hospital record returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HospitalResponse"},"example":{"data":{"ccn":"320001","trustedPerchHospitalId":"83f16f91-ec7f-4697-9274-b60e05154e25","name":"Example Medical Center","address":{"line1":"100 Hospital Drive","city":"Albuquerque","state":"NM","postalCode":"87102","country":"US"},"coordinates":{"latitude":35.0844,"longitude":-106.6504},"phone":"505-555-0100","hospitalType":"Acute Care Hospital","profile":{"display_name":"Example Medical Center","slug":"example-medical-center","health_system":"Example Health","website":"https://example.org","trauma_level":"Level I","teaching_hospital":true,"magnet_status":false,"bed_count":450,"emergency_department":true,"published":true},"links":{"housingSearch":"https://trustedperch.com/find-housing?hospitalCcn=320001"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/HospitalNotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/hospitals/{ccn}/housing":{"get":{"tags":["Housing"],"summary":"Get nearby verified housing","operationId":"getNearbyHousingByHospitalCcn","description":"Returns published TrustedPerch listings at verified properties\nnear the requested hospital.\n","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/Ccn"},{"name":"radiusMiles","in":"query","required":false,"description":"Search radius in miles.","schema":{"type":"integer","minimum":1,"maximum":50,"default":15}},{"name":"limit","in":"query","required":false,"description":"Maximum number of listings to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":12}}],"responses":{"200":{"description":"Nearby housing returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HousingResponse"},"example":{"data":{"hospital":{"ccn":"320001","name":"Example Medical Center"},"radiusMiles":15,"count":1,"listings":[{"listingId":"8a8c6c22-e544-44f4-8052-c5a1c175c8bf","title":"Furnished apartment near Example Medical Center","city":"Albuquerque","state":"NM","postalCode":"87102","distanceMiles":1.8,"monthlyRentCents":185000,"depositCents":50000,"unitType":"apartment","bedrooms":1,"bathrooms":1,"maxOccupancy":2,"petPolicy":"case_by_case","minimumStayNights":30,"amenities":["Wi-Fi","In-unit laundry","Parking"],"imageUrl":"https://example.trustedperch.com/listing-image.webp","listingUrl":"https://trustedperch.com/listings/8a8c6c22-e544-44f4-8052-c5a1c175c8bf"}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/HospitalNotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/clinivibes/hospital-insights":{"post":{"tags":["Hospital Insights"],"summary":"Submit aggregate hospital insights","operationId":"upsertClinivibesHospitalInsights","description":"Creates or updates the aggregate CliniVibes insight record for a hospital.\n\nA later request for the same CCN replaces the previous aggregate summary.\nReuse an Idempotency-Key only when retrying the same update.\n","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable unique identifier for this version of the update.\nReuse the same value when retrying the same request.\n","schema":{"type":"string","minLength":1},"example":"clinivibes-320001-2026-07-15T03:00:00Z"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HospitalInsightInput"},"example":{"ccn":"320001","externalHospitalId":"2c05545b-7f90-4697-8cc9-8dc3394cf950","overallRating":3.9,"recommendationPercent":89,"reviewCount":9,"specialties":[{"name":"ICU","reviewCount":4,"rating":4.1},{"name":"Emergency Department","reviewCount":3,"rating":3.7}],"reportedRatios":[{"specialty":"ICU","shift":"night","ratio":"1:2","sampleSize":3},{"specialty":"Med/Surg","shift":"mixed","ratio":"1:5","sampleSize":2}],"ehrSystems":["Cerner"],"scrubColors":["Black"],"travelerFriendlySummary":"Most reviewers report traveler-friendly scheduling and\nadequate ancillary support.\n","sourceUrl":"https://www.clinivibes.com/reviews/2c05545b-7f90-4697-8cc9-8dc3394cf950","sourceUpdatedAt":"2026-07-15T03:00:00Z"}}}},"responses":{"200":{"description":"Insight accepted or duplicate request recognized","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/InsightAcceptedResponse"},{"$ref":"#/components/schemas/InsightDuplicateResponse"}]},"examples":{"accepted":{"summary":"New insight accepted","value":{"data":{"accepted":true,"duplicate":false,"requestId":"90d605d9-dd09-40e9-a2f5-927659410622","insightId":"44d20367-7529-4c8d-89e3-a112571716c7","hospital":{"ccn":"320001","name":"Example Medical Center"},"updatedAt":"2026-07-15T03:10:24.615Z"}}},"duplicate":{"summary":"Duplicate retry","value":{"data":{"accepted":true,"duplicate":true,"requestId":"90d605d9-dd09-40e9-a2f5-927659410622"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/HospitalNotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Send the partner API key using:\n\nAuthorization: Bearer YOUR_PARTNER_API_KEY\n"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative partner API key header."}},"parameters":{"Ccn":{"name":"ccn","in":"path","required":true,"description":"Six-digit CMS Certification Number.","schema":{"type":"string","pattern":"^[0-9]{6}$"},"example":"320001"}},"schemas":{"Address":{"type":"object","required":["line1","city","state","postalCode","country"],"properties":{"line1":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string","example":"US"}}},"Coordinates":{"type":"object","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}}},"HospitalProfile":{"type":"object","properties":{"display_name":{"type":["string","null"]},"slug":{"type":["string","null"]},"health_system":{"type":["string","null"]},"website":{"type":["string","null"],"format":"uri"},"trauma_level":{"type":["string","null"]},"teaching_hospital":{"type":["boolean","null"]},"magnet_status":{"type":["boolean","null"]},"bed_count":{"type":["integer","null"],"minimum":0},"emergency_department":{"type":["boolean","null"]},"published":{"type":["boolean","null"]}}},"Hospital":{"type":"object","required":["ccn","trustedPerchHospitalId","name","address","coordinates","profile","links"],"properties":{"ccn":{"type":"string","pattern":"^[0-9]{6}$"},"trustedPerchHospitalId":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/Address"},"coordinates":{"$ref":"#/components/schemas/Coordinates"},"phone":{"type":["string","null"]},"hospitalType":{"type":["string","null"]},"profile":{"$ref":"#/components/schemas/HospitalProfile"},"links":{"type":"object","required":["housingSearch"],"properties":{"housingSearch":{"type":"string","format":"uri"}}}}},"HospitalResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Hospital"}}},"HospitalSummary":{"type":"object","required":["ccn","name"],"properties":{"ccn":{"type":"string","pattern":"^[0-9]{6}$"},"name":{"type":"string"}}},"HousingListing":{"type":"object","required":["listingId","title","city","state","postalCode","distanceMiles","monthlyRentCents","unitType","bedrooms","bathrooms","maxOccupancy","petPolicy","minimumStayNights","amenities","listingUrl"],"properties":{"listingId":{"type":"string","format":"uuid"},"title":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"distanceMiles":{"type":"number","minimum":0},"monthlyRentCents":{"type":"integer","minimum":0,"description":"Monthly rent expressed in cents."},"depositCents":{"type":["integer","null"],"minimum":0,"description":"Deposit expressed in cents."},"unitType":{"type":"string"},"bedrooms":{"type":"number","minimum":0},"bathrooms":{"type":"number","minimum":0},"maxOccupancy":{"type":"integer","minimum":1},"petPolicy":{"type":"string"},"minimumStayNights":{"type":"integer","minimum":1},"amenities":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":["string","null"],"format":"uri"},"listingUrl":{"type":"string","format":"uri"}}},"HousingResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["hospital","radiusMiles","count","listings"],"properties":{"hospital":{"$ref":"#/components/schemas/HospitalSummary"},"radiusMiles":{"type":"integer","minimum":1,"maximum":50},"count":{"type":"integer","minimum":0},"listings":{"type":"array","items":{"$ref":"#/components/schemas/HousingListing"}}}}}},"SpecialtyInsight":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"reviewCount":{"type":"integer","minimum":0},"rating":{"type":["number","null"],"minimum":0,"maximum":5}}},"ReportedRatio":{"type":"object","required":["specialty","ratio"],"properties":{"specialty":{"type":"string"},"shift":{"type":"string","enum":["day","night","mixed","unknown"]},"ratio":{"type":"string","pattern":"^\\d+\\s*:\\s*\\d+$","example":"1:2"},"sampleSize":{"type":"integer","minimum":0}}},"HospitalInsightInput":{"type":"object","required":["ccn","reviewCount","sourceUrl"],"properties":{"ccn":{"type":"string","pattern":"^[0-9]{6}$"},"externalHospitalId":{"type":"string","format":"uuid"},"overallRating":{"type":["number","null"],"minimum":0,"maximum":5},"recommendationPercent":{"type":["number","null"],"minimum":0,"maximum":100},"reviewCount":{"type":"integer","minimum":0},"specialties":{"type":"array","items":{"$ref":"#/components/schemas/SpecialtyInsight"}},"reportedRatios":{"type":"array","items":{"$ref":"#/components/schemas/ReportedRatio"}},"ehrSystems":{"type":"array","items":{"type":"string"}},"scrubColors":{"type":"array","items":{"type":"string"}},"travelerFriendlySummary":{"type":["string","null"]},"sourceUrl":{"type":"string","format":"uri","pattern":"^https://"},"sourceUpdatedAt":{"type":["string","null"],"format":"date-time"}}},"InsightAcceptedResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["accepted","duplicate","requestId","insightId","hospital","updatedAt"],"properties":{"accepted":{"type":"boolean","const":true},"duplicate":{"type":"boolean","const":false},"requestId":{"type":"string","format":"uuid"},"insightId":{"type":"string","format":"uuid"},"hospital":{"$ref":"#/components/schemas/HospitalSummary"},"updatedAt":{"type":"string","format":"date-time"}}}}},"InsightDuplicateResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["accepted","duplicate","requestId"],"properties":{"accepted":{"type":"boolean","const":true},"duplicate":{"type":"boolean","const":true},"requestId":{"type":"string","format":"uuid"}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["missing_api_key","invalid_api_key","partner_inactive","insufficient_scope","invalid_ccn","invalid_json","invalid_payload","missing_idempotency_key","hospital_not_found","hospital_lookup_failed","housing_lookup_failed","mapping_failed","insight_save_failed"]},"message":{"type":"string"}}}}}},"responses":{"BadRequest":{"description":"Invalid request, malformed JSON, or missing idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Inactive credential or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"HospitalNotFound":{"description":"Hospital CCN not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"hospital_not_found","message":"TrustedPerch has no hospital for this CCN."}}}}},"ValidationError":{"description":"Request payload failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"TrustedPerch processing or database error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}