Organizations and Locations

Use this guide to model organizations and the places they use across scheduling, referrals, clinical care, and billing. Connect facilities to the organizations and services that use them, and choose the appropriate reference for each workflow.

A clinic can be the facility selected during booking and reported on a claim, while a room within it is reserved and recorded on the Encounter. These references can point to the same Location when that is sufficient; add detail when the workflow needs it.

Places, Organizations, and Services​

An additional clinic usually needs another Location. Add an Organization when the organizational distinction itself matters, such as a separately managed division, billing entity, or tenant. Multiple Locations can share one managing Organization. See Modeling Provider Organizations for the broader directory model.

Some integrations use practice location to mean an Organization. Health Gorilla and ScriptSure model their practice locations this way. A clinic may need both an integration-specific Organization and a Location for scheduling, clinical care, or billing. Maintain each record according to its integration's mapping, and synchronize shared details through your application or integration workflow.

Use Organization.partOf for organizational subdivisions. For relationships between distinct organizations, such as partnerships or network participation, use OrganizationAffiliation. See Modeling Provider Networks for insurance network relationships.

Organizations and Tenant Boundaries​

Projects provide Medplum's primary data-isolation boundary. Organizations within a project can share PHI according to the project's access policies. An Organization can represent a tenant, with selected patient data, including the Patient resource itself, shared across tenants by design.

• Access rules: Define separation and sharing through AccessPolicy and ProjectMembership. Configure those policies to enforce the intended access to patient records; managingOrganization and partOf describe directory relationships.

• Patient enrollment: In Medplum's standard patient-enrollment model, related clinical resources can inherit the Patient's tenant assignments. If you need to share the Patient record while keeping clinical records separate, account for that inheritance in the access design. See Multi-Tenant Access Control and the Access Control Decision Guide.

• Shared directories: Organizations can serve as shared directory entries for payers, pharmacies, laboratories, and networks. For example, practices can share a pharmacy directory while protecting each patient's pharmacy preference separately. See Sharing pharmacy Organizations.

For project isolation and explicitly configured sharing between projects, see Projects.

Choose the Location Detail You Need​

For a simple outpatient practice, start with one clinic Location. Add detail as the workflow requires:

• Rooms or beds: Reserve their capacity or document where care occurred.
• Campus or building: Group or identify the places your application uses.

In this example, West Clinic occupies one building on a campus. The clinic is the service facility used for booking and billing, and Room 201 has its own reservable calendar.

  flowchart BT
    room["Location/room-201<br/>Exam room 201"] -->|partOf| clinic["Location/west-clinic<br/>West Clinic building"]
    clinic -->|partOf| campus["Location/west-campus<br/>West Campus"]
    clinic -->|managingOrganization| org["Organization/example-care<br/>Example Care"]
    campus -->|managingOrganization| org

Choose the levels that describe your practice. A standalone clinic can be the root Location, and a clinic occupying part of a building can represent just that space. Use Device.location to place equipment within the hierarchy.

Populate each Location with the address fields its workflows require. When a query needs to include related places, explicitly follow the relevant partOf relationships.

Describe Each Location​

See FHIR R4 Location fields for the full definitions and Billing Facility and Place of Service for claim-specific mappings.

Choose the Reference for Each Workflow​

For one visit at West Clinic, the Appointment and Claim identify the clinic as the facility. The room reservation and Encounter both identify Room 201.

  flowchart LR
    subgraph records["Workflow Records"]
        claim["Claim"]
        appointment["Appointment"]
        encounter["Encounter"]
    end

    subgraph places["Locations"]
        clinic["West Clinic"]
        room["Room 201"]
    end

    claim -->|Facility for billing| clinic
    appointment -->|Service facility| clinic
    appointment -->|Reserved room| room
    encounter -->|Where care occurred| room

The room reservation uses Slots on the room's Schedule. Your clinical and billing workflows create the Encounter and Claim and set their locations.

Medplum records the service facility in FHIR's Appointment.supportingInformation using a marker defined by SchedulingSiteURI. Use toAppointmentSiteReference to create the marked reference and getAppointmentSite to read it, both from @medplum/core.

For referrals and orders, choose the recipient through ServiceRequest.performer and specify a requested physical site through ServiceRequest.locationReference when needed. See Recipients and Referral Packages for choosing the destination.

Scheduling​

• Room reservations: Reserve room capacity by including the room's Schedule when finding and booking time. Availability is implicit: Medplum creates Slots only for booked, held, or blocked time. See Defining Availability.

• Hours by site: For different hours at each site, use separate HealthcareServices with a shared practitioner Schedule and service-specific overrides where needed. See Choosing the actor.

• Time zones: Set the availability time zone on the Schedule or HealthcareService, with the Schedule actor's time zone as the fallback. To use a facility's time zone for a practitioner, configure it explicitly. See Facility Time Zones.

• Closures: When a facility closes or changes hours, update the affected Schedules or block the unavailable time on each calendar.

• Licensure: Use jurisdiction Locations for licensed areas and clinic Locations for facility assignments. Follow the service-specific licensure model when needed, and enforce required eligibility checks in the application's controlled booking path.

SchedulingConfigWorkspace can create its own facility-assignment PractitionerRole with organization unset, alongside directory roles. The React booking UI combines locations from each provider's active roles; see Configuration ownership and Facility matching. Enforce access to the underlying data with AccessPolicy. Choose how to use the UI in the Scheduling Decision Guide.

Clinical Care​

Use Encounter.location at the level the clinical workflow needs. Its entries can include status and period to distinguish planned locations from actual presence and to record movement during care.

Encounter.serviceProvider identifies the organization responsible for the encounter's services. See FHIR R4 Encounter location and the Chart Data Model.

Billing Facility and Place of Service​

Claim.facility identifies the Location where services were provided. A place-of-service code classifies the setting for billing. The facility, billing provider, and place-of-service classification are separate inputs.

The claim-building workflow must choose the facility appropriate for the submission and supply its required name, address, and identifiers on that Location. The Candid and Stedi integrations read those details directly from the selected record. Depending on the submission requirements, this may be the clinic containing the encounter room or another relevant facility.

FHIR R4 allows a service line's Claim.item.location[x] to be a coded setting, an address, or a Location reference. For Medplum's Candid and Stedi professional-claim integrations, set the place-of-service code explicitly on Claim.item.locationCodeableConcept. See FHIR Claim definitions, Candid facility mapping, and Stedi facility mapping for the applicable requirements and fallback behavior.

Telehealth​

Keep the visit's delivery method separate from where its participants are located. A remote visit still has location information relevant to clinical care, eligibility, and billing.

FHIR R4 describes a virtual encounter using Encounter.class and, when useful, an Encounter.location reference to a generic setting such as the patient's home. Use mode = kind for this shared category, or mode = instance for a specific place. Capture the patient's actual location as needed for the visit. See FHIR R4 virtual encounters.

For US professional claims, CMS distinguishes telehealth at home from telehealth elsewhere. Use the CMS definitions and the relevant payer requirements for that classification.

Choose how the application captures and confirms these facts, then maps them into clinical and billing records. Offer a physical facility choice for a virtual visit only when that place is relevant to the workflow.