HealthcareService

Overview

The HealthcareService resource describes the services offered by healthcare organizations at specific locations. It defines what services are available, when they're available, and how to access them within provider networks.

Key Use Cases:

Find available services at healthcare locations
Discover services by specialty or category
Locate services within insurance networks
Verify service availability and contact information

Relationships to Other Resources:

Organization - Organizations that provide the services
Location - Physical locations where services are offered
PractitionerRole - Practitioners who deliver the services
Endpoint - Technical endpoints for accessing services

Resource Schema

Key fields in the HealthcareService resource:

{
  "resourceType": "HealthcareService",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/service-id",
      "value": "SVC-123"
    }
  ],
  "active": true,
  "providedBy": {
    "reference": "Organization/org-123",
    "display": "Sacramento Medical Center"
  },
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/service-category",
          "code": "35",
          "display": "Mental Health"
        }
      ]
    }
  ],
  "type": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "394913002",
          "display": "Psychotherapy"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "system": "http://nucc.org/provider-taxonomy",
          "code": "103T00000X",
          "display": "Psychologist"
        }
      ]
    }
  ],
  "location": [
    {
      "reference": "Location/loc-456",
      "display": "Mental Health Center"
    }
  ],
  "name": "Adult Psychotherapy Services",
  "comment": "Individual and group therapy sessions for adults",
  "telecom": [
    {
      "system": "phone",
      "value": "(916) 555-0150",
      "use": "work"
    }
  ],
  "coverageArea": [
    {
      "reference": "Location/coverage-area-ca"
    }
  ],
  "serviceProvisionCode": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/service-provision-conditions",
          "code": "free",
          "display": "Free"
        }
      ]
    }
  ],
  "availableTime": [
    {
      "daysOfWeek": ["mon", "tue", "wed", "thu", "fri"],
      "availableStartTime": "09:00:00",
      "availableEndTime": "17:00:00"
    }
  ]
}

Key Fields:

providedBy - Organization offering the service
category - High-level service category
type - Specific type of service
specialty - Medical specialty associated with service
location - Where the service is provided
availableTime - When the service is available

Operations

Read

Retrieve a specific healthcare service by ID.

Production
Preview

GET /HealthcareService/{id}

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

GET /HealthcareService/{id}

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

Search

Search for healthcare services using various criteria.

GET Method

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

Production
Preview

GET /HealthcareService?parameter=value

GET /HealthcareService?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production
Preview

POST /HealthcareService/_search

POST /HealthcareService/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
`location`	reference	No	Location where service is provided	`location=Location/loc-456`
`name`	string	No	Service name (partial match)	`name=Therapy`
`organization`	reference	No	Organization providing service	`organization=Organization/org-123`
`service-category`	token	No	Service category	`service-category=35`
`service-type`	token	No	Specific service type	`service-type=394913002`
`specialty`	token	No	Medical specialty	`specialty=103T00000X`

Common Search Patterns

Find services by category:

GET /HealthcareService?service-category=35&_count=10

Search by organization:

GET /HealthcareService?organization=Organization/org-123

Find services at location:

GET /HealthcareService?location=Location/loc-456

Search by specialty:

GET /HealthcareService?specialty=103T00000X

Examples

Request Examples

Production
Preview

Find mental health services
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/HealthcareService/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "service-category=35&_count=10"

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

Find services by name and location
curl -X POST https://fhir.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/HealthcareService/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Cardiology&location.address-city=Sacramento"

Find mental health services
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/HealthcareService/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "service-category=35&_count=10"

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

Find services by name and location
curl -X POST https://fhirtest.netsmartcloud.com/payer/provider-directory/v2/{tenant-id}/HealthcareService/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "name=Cardiology&location.address-city=Sacramento"

Response Examples

Successful Search Response

HealthcareService Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "HealthcareService",
        "id": "svc-123",
        "active": true,
        "providedBy": {
          "reference": "Organization/org-456",
          "display": "Community Mental Health Center"
        },
        "category": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/service-category",
                "code": "35",
                "display": "Mental Health"
              }
            ]
          }
        ],
        "type": [
          {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "394913002",
                "display": "Psychotherapy"
              }
            ]
          }
        ],
        "location": [
          {
            "reference": "Location/loc-789",
            "display": "Downtown Clinic"
          }
        ],
        "name": "Individual Therapy Services",
        "telecom": [
          {
            "system": "phone",
            "value": "(916) 555-0175",
            "use": "work"
          }
        ],
        "availableTime": [
          {
            "daysOfWeek": ["mon", "tue", "wed", "thu", "fri"],
            "availableStartTime": "08:00:00",
            "availableEndTime": "18:00:00"
          }
        ]
      }
    }
  ]
}

Integration Patterns

Common Workflows

1. Find Services at Healthcare Facility

# Step 1: Find organization
GET /Organization?name=Medical Center&type=prov

# Step 2: Get all services at organization
GET /HealthcareService?organization=Organization/org-123

# Step 3: Get location details for services
GET /Location/loc-456

2. Specialty Service Discovery

# Step 1: Find services by specialty
GET /HealthcareService?specialty=207RC0000X

# Step 2: Get practitioners providing services
GET /PractitionerRole?service=HealthcareService/svc-123

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

Organization - Organizations providing services
Location - Where services are provided
PractitionerRole - Practitioners delivering services
Endpoint - Technical access to services

Include Parameters

Use _include to fetch related resources:

# Get services with their locations
GET /HealthcareService?organization=Organization/org-123&_include=HealthcareService:location

# Get services with providing organization
GET /HealthcareService?service-category=35&_include=HealthcareService:organization

Error Handling

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