Practitioner

Overview

The Practitioner resource represents individual healthcare providers such as doctors, nurses, therapists, and other clinical professionals. Practitioners are the people who deliver healthcare services within provider networks.

Key Use Cases:

Find healthcare providers by name or specialty
Locate practitioners by geographic area
Verify provider credentials and identifiers
Discover provider contact information

Relationships to Other Resources:

PractitionerRole - Defines roles and positions practitioners hold at organizations
Organization - Organizations that employ or contract with practitioners
Location - Physical locations where practitioners provide services
HealthcareService - Services that practitioners provide

Resource Schema

Key fields in the Practitioner resource:

{
  "resourceType": "Practitioner",
  "id": "string",
  "identifier": [
    {
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "1234567890"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "string",
      "given": ["string"],
      "prefix": ["Dr.", "Mr.", "Ms."],
      "suffix": ["MD", "RN", "PhD"]
    }
  ],
  "telecom": [
    {
      "system": "phone|email|fax",
      "value": "string",
      "use": "work|home|mobile"
    }
  ],
  "address": [
    {
      "use": "work|home",
      "line": ["string"],
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string"
    }
  ],
  "gender": "male|female|other|unknown",
  "birthDate": "YYYY-MM-DD",
  "qualification": [
    {
      "code": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0360",
            "code": "MD",
            "display": "Doctor of Medicine"
          }
        ]
      },
      "issuer": {
        "reference": "Organization/medical-board"
      }
    }
  ]
}

Key Fields:

id - Unique identifier for the practitioner
identifier - External identifiers (NPI, state license numbers)
name - Practitioner's name components
telecom - Contact information
address - Practice addresses
qualification - Professional credentials and certifications

Operations

Read

Retrieve a specific practitioner by ID.

Production
Preview

GET /Practitioner/{id}

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

GET /Practitioner/{id}

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

Search

Search for practitioners using various criteria.

GET Method

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

Production
Preview

GET /Practitioner?parameter=value

GET /Practitioner?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production
Preview

POST /Practitioner/_search

POST /Practitioner/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
`family`	string	No	Family (last) name	`family=Smith`
`given`	string	No	Given (first) name	`given=John`
`identifier`	token	No	NPI or other identifier	`identifier=1234567890`
`name`	string	No	Any part of practitioner name	`name=John Smith`

Common Search Patterns

Find practitioners by last name:

GET /Practitioner?family=Smith&_count=10

Search by full name:

GET /Practitioner?name=John Smith

Find by NPI number:

GET /Practitioner?identifier=1234567890

Search by first and last name:

GET /Practitioner?given=John&family=Smith

Examples

Request Examples

Production
Preview

Search by family name
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Practitioner/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "family=Smith&_count=10"

Search by NPI identifier
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Practitioner/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "identifier=1234567890"

Search by full name
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Practitioner/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Dr.%20Sarah%20Johnson"

Search by family name
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Practitioner/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "family=Smith&_count=10"

Search by NPI identifier
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Practitioner/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "identifier=1234567890"

Search by full name
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/Practitioner/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Dr.%20Sarah%20Johnson"

Response Examples

Successful Search Response

Practitioner Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "entry": [
    {
      "resource": {
        "resourceType": "Practitioner",
        "id": "prac-123",
        "identifier": [
          {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "1234567890"
          }
        ],
        "active": true,
        "name": [
          {
            "use": "official",
            "family": "Smith",
            "given": ["John", "Michael"],
            "prefix": ["Dr."],
            "suffix": ["MD"]
          }
        ],
        "telecom": [
          {
            "system": "phone",
            "value": "(916) 555-0123",
            "use": "work"
          },
          {
            "system": "email",
            "value": "j.smith@example.com",
            "use": "work"
          }
        ],
        "gender": "male",
        "qualification": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://terminology.hl7.org/CodeSystem/v2-0360",
                  "code": "MD",
                  "display": "Doctor of Medicine"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Individual Practitioner Response

Single Practitioner Resource
{
  "resourceType": "Practitioner",
  "id": "prac-456",
  "identifier": [
    {
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "9876543210"
    },
    {
      "system": "http://example.org/state-license",
      "value": "CA-12345"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Johnson",
      "given": ["Sarah", "Elizabeth"],
      "prefix": ["Dr."],
      "suffix": ["MD", "PhD"]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "(415) 555-0199",
      "use": "work"
    }
  ],
  "address": [
    {
      "use": "work",
      "line": ["123 Medical Center Dr"],
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    }
  ],
  "gender": "female",
  "qualification": [
    {
      "code": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0360",
            "code": "MD",
            "display": "Doctor of Medicine"
          }
        ]
      }
    }
  ]
}

Integration Patterns

Common Workflows

1. Find Practitioners by Specialty and Location

# Step 1: Search for practitioner roles by specialty
GET /PractitionerRole?specialty=207R00000X&location.address-state=CA

# Step 2: Get practitioner details using _include
GET /PractitionerRole?specialty=207R00000X&_include=PractitionerRole:practitioner

# Step 3: Get specific practitioner
GET /Practitioner/prac-123

2. Verify Provider Credentials

# Step 1: Find practitioner by NPI
GET /Practitioner?identifier=1234567890

# Step 2: Get their roles and organizations
GET /PractitionerRole?practitioner=Practitioner/prac-123

# Step 3: Verify organization affiliations
GET /Organization/org-456

PractitionerRole - Roles and positions practitioners hold
Organization - Organizations that employ practitioners
Location - Where practitioners provide services
HealthcareService - Services practitioners provide

Include Parameters

Use _include and _revinclude to fetch related resources:

# Get practitioner with their roles
GET /Practitioner?family=Smith&_revinclude=PractitionerRole:practitioner

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

Error Handling

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

Practitioner-Specific Error Scenarios

404 Not Found: Practitioner ID doesn't exist or practitioner is inactive
400 Bad Request: Invalid search parameters (e.g., using specialty on Practitioner instead of PractitionerRole)
Empty Results: No practitioners match the search criteria

Troubleshooting Tips

No Results for Specialty Search: Use PractitionerRole resource instead of Practitioner for specialty-based searches
Name Variations: Try searching with partial names or different name components
Identifier Issues: Verify NPI format and ensure leading zeros are included

Overview​

Resource Schema​

Operations​

Read​

Search​

GET Method​

POST Method​

Search Parameters​

Common Search Patterns​

Examples​

Request Examples​

Response Examples​

Successful Search Response​

Individual Practitioner Response​

Integration Patterns​

Common Workflows​

Related Resources​

Include Parameters​

Error Handling​

Practitioner-Specific Error Scenarios​

Troubleshooting Tips​

Supported Profiles​