PractitionerRole

Overview

The PractitionerRole resource defines the roles, specialties, and relationships that practitioners have with organizations, locations, and healthcare services. This resource connects individual practitioners to their professional contexts within provider networks.

Key Use Cases:

Find practitioners by specialty and location
Discover provider roles within organizations
Locate practitioners accepting specific insurance plans
Verify practitioner network affiliations and specialties

Relationships to Other Resources:

Practitioner - Individual healthcare providers performing the role
Organization - Organizations where practitioners work
Location - Physical locations where practitioners provide services
HealthcareService - Services practitioners provide in their roles
Endpoint - Technical endpoints for practitioner services

Resource Schema

Key fields in the PractitionerRole resource:

{
  "resourceType": "PractitionerRole",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/provider-id",
      "value": "PROV-123"
    }
  ],
  "active": true,
  "period": {
    "start": "2020-01-01",
    "end": "2025-12-31"
  },
  "practitioner": {
    "reference": "Practitioner/prac-123",
    "display": "Dr. John Smith"
  },
  "organization": {
    "reference": "Organization/org-456",
    "display": "Sacramento Medical Center"
  },
  "code": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/practitioner-role",
          "code": "doctor",
          "display": "Doctor"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "system": "http://nucc.org/provider-taxonomy",
          "code": "207R00000X",
          "display": "Internal Medicine"
        }
      ]
    }
  ],
  "location": [
    {
      "reference": "Location/loc-789",
      "display": "Main Campus"
    }
  ],
  "healthcareService": [
    {
      "reference": "HealthcareService/svc-101"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "(916) 555-0123",
      "use": "work"
    }
  ],
  "availableTime": [
    {
      "daysOfWeek": ["mon", "tue", "wed", "thu", "fri"],
      "availableStartTime": "08:00:00",
      "availableEndTime": "17:00:00"
    }
  ]
}

Key Fields:

practitioner - Reference to the individual practitioner
organization - Organization where the role is performed
specialty - Medical specialties for this role
location - Where the practitioner provides services
code - Type of role (doctor, nurse, etc.)
availableTime - When the practitioner is available

Operations

Read

Retrieve a specific practitioner role by ID.

Production
Preview

GET /PractitionerRole/{id}

Example Request
curl -X GET https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/role-123 \
    -H "Accept: application/fhir+json"

GET /PractitionerRole/{id}

Example Request
curl -X GET https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/role-123 \
    -H "Accept: application/fhir+json"

Search

Search for practitioner roles using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production
Preview

GET /PractitionerRole?parameter=value

GET /PractitionerRole?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production
Preview

POST /PractitionerRole/_search

POST /PractitionerRole/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
`location`	reference	No	Location where services are provided	`location=Location/loc-789`
`network`	reference	No	Network organization	`network=Organization/network-123`
`organization`	reference	No	Organization where role is performed	`organization=Organization/org-456`
`practitioner`	reference	No	Specific practitioner	`practitioner=Practitioner/prac-123`
`role`	token	No	Practitioner role type	`role=doctor`
`service`	reference	No	Healthcare service provided	`service=HealthcareService/svc-101`
`specialty`	token	No	Medical specialty	`specialty=207R00000X`

Common Search Patterns

Find practitioners by specialty:

GET /PractitionerRole?specialty=207R00000X&_count=10

Search by organization:

GET /PractitionerRole?organization=Organization/org-456

Find practitioners at specific location:

GET /PractitionerRole?location=Location/loc-789

Search by specialty and location:

GET /PractitionerRole?specialty=207RC0000X&location.address-state=CA

Examples

Request Examples

Production
Preview

Find cardiologists in California
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "specialty=207RC0000X&location.address-state=CA&_count=10"

Search by organization with practitioner details
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "organization=Organization/org-456&_include=PractitionerRole:practitioner"

Find practitioners at specific location
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "location=Location/loc-789&_include=PractitionerRole:practitioner"

Find cardiologists in California
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "specialty=207RC0000X&location.address-state=CA&_count=10"

Search by organization with practitioner details
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "organization=Organization/org-456&_include=PractitionerRole:practitioner"

Find practitioners at specific location
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/PractitionerRole/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "location=Location/loc-789&_include=PractitionerRole:practitioner"

Response Examples

Successful Search Response

PractitionerRole Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "PractitionerRole",
        "id": "role-123",
        "active": true,
        "practitioner": {
          "reference": "Practitioner/prac-456",
          "display": "Dr. Sarah Johnson"
        },
        "organization": {
          "reference": "Organization/org-789",
          "display": "Sacramento Cardiology Group"
        },
        "code": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/practitioner-role",
                "code": "doctor",
                "display": "Doctor"
              }
            ]
          }
        ],
        "specialty": [
          {
            "coding": [
              {
                "system": "http://nucc.org/provider-taxonomy",
                "code": "207RC0000X",
                "display": "Cardiovascular Disease"
              }
            ]
          }
        ],
        "location": [
          {
            "reference": "Location/loc-101",
            "display": "Main Office"
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "(916) 555-0199",
            "use": "work"
          }
        ]
      }
    }
  ]
}

Integration Patterns

Common Workflows

1. Find Specialists by Location

# Step 1: Search for practitioner roles by specialty and location
GET /PractitionerRole?specialty=207RC0000X&location.address-city=Sacramento

# Step 2: Get practitioner details
GET /Practitioner/prac-456

# Step 3: Get location details
GET /Location/loc-101

2. Discover Organization Providers

# Step 1: Find all roles at organization
GET /PractitionerRole?organization=Organization/org-789

# Step 2: Include practitioner details in single request
GET /PractitionerRole?organization=Organization/org-789&_include=PractitionerRole:practitioner

# Step 3: Get available services
GET /HealthcareService?organization=Organization/org-789

Practitioner - Individual healthcare providers
Organization - Organizations where practitioners work
Location - Service locations
HealthcareService - Services provided by practitioners

Include Parameters

Use _include to fetch related resources:

# Get roles with practitioner details
GET /PractitionerRole?specialty=cardiology&_include=PractitionerRole:practitioner

# Get roles with organization and location details
GET /PractitionerRole?practitioner=Practitioner/prac-123&_include=PractitionerRole:organization&_include=PractitionerRole:location

Error Handling

The PractitionerRole resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.