Recommendations for querying Practitioners who are licensed to practice in a given state medplum #support

Recommendations for querying Practitioners who are...

Stephen Henderson

12/15/2025, 2:58 PM

Hi, looking for recommendations on how best to structure my FHIR resources for the following use case. We collect some intake from the patient, and based on their state we want to assign their care to some practitioner in our system who is licensed to practice in their state. Initially we may have a smaller pool of practitioners to choose from (maybe 2-3) so it can be more manual, but this won't scale well long term. In my research I've come up with a few options: ### 1. State-specific CareTeams - Create

practitioners-ny

practitioners-ca

, etc. - Easily queryable -

CareTeam.participant.period

tracks validity - Con: 50+ CareTeams to manage, no license number storage ### 2. Custom identifiers on Practitioner - Add

Practitioner.identifier

with system per state (

https://api.withflex.com/fhir/license/NY

) - Query:

GET /Practitioner?identifier=system|

Identifier.period

for validity, filter expired in app code - Con: Manual identifier entry during onboarding (especially cumbersome for practitionrs licensed in lots of states) ### 3. Practitioner.qualification - Use native

qualification.code

(MD/DO/RN) +

qualification.issuer.display

= state - Best Medplum UI support for practitioner self-entry - Con: No built-in search by state—requires custom SearchParameter or app-side filtering ### 4. PractitionerRole + Da Vinci Plan-Net extension - Add

PractitionerRole

resource with

qualification.whereValid

extension for state codes - Most standards-compliant for payer/directory interoperability - Con: Overkill unless building provider directory; requires custom SearchParameter

finnbergquist

12/15/2025, 9:46 PM

Hi @Stephen Henderson , for this use case I would recommend creating Location resources for each state and then create PractitionerRole resources that link each Practitioner to the states where they're licensed using Location resources. Then, when you have a Patient and need to find which Practitioners are eligible to be assigned to that Patient based on licensure, you could query that using the

location

search param for PractitionerRole while including Practitioner:

finnbergquist

12/15/2025, 9:46 PM

Copy code

// Find all active practitioners licensed in NY
const results = await medplum.searchResources('PractitionerRole', {
  location: 'Location/location-ny',
  active: 'true',
  _revinclude: 'Practitioner:practitioner'
});

finnbergquist

12/15/2025, 9:47 PM

Where you have

Copy code

// Location for each state (create once, reuse across practitioners)
const nyLocation: Location = {
  resourceType: 'Location',
  id: 'location-ny',
  name: 'New York',
  address: {
    state: 'NY',
    country: 'US'
  },
  identifier: [{
    system: 'http://terminology.hl7.org/CodeSystem/v2-0347',
    value: 'NY'
  }]
};

// PractitionerRole linking practitioner to location
const role: PractitionerRole = {
  resourceType: 'PractitionerRole',
  practitioner: { reference: 'Practitioner/dr-smith' },
  location: [{ reference: 'Location/location-ny' }],
  period: {
    start: '2024-01-01',
    end: '2026-01-01' // License expiration
  },
  active: true
};

Stephen Henderson

12/16/2025, 2:11 PM

Ah didn't see the Location resoucre, this is great thank you!

45 Views

Previous Next