Schedule

Overview

Purpose

The Schedule resource represents a container for time slots that define when a healthcare service, practitioner, location, or device is available for appointments. It acts as a planning tool that organizes availability periods for booking appointments.

Use Cases

Query available appointment slots for practitioners or locations
Retrieve scheduling information for healthcare services
Support appointment booking workflows
Coordinate care team availability

Relationships

Practitioner - Schedules define when practitioners are available
PractitionerRole - Schedules can be associated with specific practitioner roles
Location - Schedules define availability at specific locations
HealthcareService - Schedules organize service availability
Slot - Individual time slots reference their parent schedule

Resource Schema

Key Fields

id - Unique identifier for the schedule
active - Whether the schedule is currently in use
serviceType - Type of service provided during scheduled appointments
specialty - Medical specialty associated with the schedule
actor - References to practitioners, locations, or services this schedule applies to
planningHorizon - Time period covered by the schedule
comment - Additional information about availability

JSON Example

{
  "resourceType": "Schedule",
  "id": "schedule-123",
  "active": true,
  "serviceType": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/service-type",
          "code": "124",
          "display": "General Practice"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "394814009",
          "display": "General practice"
        }
      ]
    }
  ],
  "actor": [
    {
      "reference": "Practitioner/practitioner-456",
      "display": "Dr. Jane Smith"
    },
    {
      "reference": "Location/loc-789",
      "display": "Main Clinic"
    }
  ],
  "planningHorizon": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "comment": "General practice appointments available Monday-Friday"
}

Operations

Read

Retrieve a specific schedule by ID.

Production
Preview

GET /Schedule/{id}

Example Request
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/schedule-123 \
    -H "Accept: application/fhir+json"

GET /Schedule/{id}

Example Request
curl -X GET https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/schedule-123 \
    -H "Accept: application/fhir+json"

Search

Search for schedules using various criteria.

Production
Preview

GET /Schedule?parameter=value
POST /Schedule/_search

GET /Schedule?parameter=value
POST /Schedule/_search

Search Parameters

Patient-based Search:

Parameter	Type	Required	Description	Example
`actor`	reference	Yes	Practitioner, Location, or HealthcareService reference	`actor=Practitioner/practitioner-123`
`active`	token	No	Whether the schedule is active	`active=true`
`date`	date	No	Schedule date range	`date=ge2026-03-01`
`service-type`	token	No	Type of service	`service-type=124`
`specialty`	token	No	Medical specialty	`specialty=394814009`
`_count`	number	No	Number of results per page	`_count=20`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=ge2026-01-01`
`_revinclude`	special	No	Include Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"	`_revinclude=Provenance:target`

ID-based Search:

Parameter	Type	Required	Description	Example
`_id`	token	Yes	Schedule ID	`_id=schedule-123`
`_count`	number	No	Number of results per page	`_count=20`
`_lastUpdated`	date	No	Only return resources which were last updated as specified by the given range	`_lastUpdated=ge2026-01-01`
`_revinclude`	special	No	Include Provenance resource(s) that reference the matched search results. Allowed: "Provenance:target"	`_revinclude=Provenance:target`

Create

Create a new Schedule resource.

Production
Preview

POST /Schedule

POST /Schedule

Update

Update an existing Schedule resource by its ID.

Production
Preview

PUT /Schedule/{id}

PUT /Schedule/{id}

Examples

Request Examples

Production
Preview

Search by practitioner
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "actor=Practitioner/practitioner-123&active=true"

Search by location and date
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "actor=Location/loc-456&date=ge2026-03-01"

Search by service type
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "service-type=124&_count=10"

Search by practitioner
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "actor=Practitioner/practitioner-123&active=true"

Search by location and date
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "actor=Location/loc-456&date=ge2026-03-01"

Search by service type
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "service-type=124&_count=10"

Response Examples

Successful Search Response

Schedule Search Bundle
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Schedule",
        "id": "schedule-123",
        "active": true,
        "serviceType": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/service-type",
                "code": "124",
                "display": "General Practice"
              }
            ]
          }
        ],
        "specialty": [
          {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "394814009",
                "display": "General practice"
              }
            ]
          }
        ],
        "actor": [
          {
            "reference": "Practitioner/practitioner-456",
            "display": "Dr. Jane Smith"
          },
          {
            "reference": "Location/loc-789",
            "display": "Main Clinic"
          }
        ],
        "planningHorizon": {
          "start": "2026-03-01T00:00:00Z",
          "end": "2026-03-31T23:59:59Z"
        },
        "comment": "General practice appointments available Monday-Friday"
      }
    }
  ]
}

Individual Schedule Response

Single Schedule Resource
{
  "resourceType": "Schedule",
  "id": "schedule-789",
  "active": true,
  "serviceType": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/service-type",
          "code": "57",
          "display": "Immunization"
        }
      ]
    }
  ],
  "specialty": [
    {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "408480009",
          "display": "Clinical immunology"
        }
      ]
    }
  ],
  "actor": [
    {
      "reference": "Location/loc-456",
      "display": "Community Health Center"
    }
  ],
  "planningHorizon": {
    "start": "2026-03-01T08:00:00Z",
    "end": "2026-03-31T17:00:00Z"
  },
  "comment": "Walk-in immunization clinic, no appointment necessary"
}

Empty Result Set

No Schedules Found
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

Create

Production
Preview

Create Schedule
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Schedule",
  "active": true,
  "actor": [
    {
      "reference": "Practitioner/practitioner-123"
    }
  ]
}'

Create Schedule
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Schedule",
  "active": true,
  "actor": [
    {
      "reference": "Practitioner/practitioner-123"
    }
  ]
}'

Update

Production
Preview

Update Schedule
curl -X PUT https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/{id} \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Schedule",
  "id": "{id}",
  "active": true,
  "actor": [
    {
      "reference": "Practitioner/practitioner-123"
    }
  ]
}'

Update Schedule
curl -X PUT https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Schedule/{id} \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/fhir+json" \
    -d '{
  "resourceType": "Schedule",
  "id": "{id}",
  "active": true,
  "actor": [
    {
      "reference": "Practitioner/practitioner-123"
    }
  ]
}'

Integration Patterns

Common Workflows

1. Find Available Appointment Times

# Step 1: Search for schedules by practitioner
GET /Schedule?actor=Practitioner/practitioner-123&active=true

# Step 2: Get available slots for the schedule
GET /Slot?schedule=Schedule/schedule-123&status=free

# Step 3: Book an appointment using an available slot
POST /Appointment

2. Location-Based Scheduling

# Step 1: Search for schedules at a location
GET /Schedule?actor=Location/loc-456&date=ge2026-03-01

# Step 2: Filter by service type
GET /Schedule?actor=Location/loc-456&service-type=124

# Step 3: Retrieve schedule details
GET /Schedule/schedule-789

Slot - Individual time slots within a schedule
Appointment - Booked appointments reference slots and schedules
Practitioner - Healthcare providers associated with schedules
PractitionerRole - Specific roles that have schedules
Location - Physical locations where scheduled services occur
HealthcareService - Services that have associated schedules

Error Handling

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

Schedule-Specific Error Scenarios

404 Not Found: Schedule ID doesn't exist or schedule is inactive
400 Bad Request: Invalid search parameters or malformed queries
Empty Results: No schedules match the search criteria

Troubleshooting Tips

Empty Results: Verify the actor reference exists and is active
Invalid Parameters: Ensure date formats follow FHIR specifications (YYYY-MM-DD)
Performance Issues: Use _count parameter to limit result sets

Supported Profiles

HL7 FHIR R4 Schedule

Overview​

Purpose​

Use Cases​

Relationships​

Resource Schema​

Key Fields​

JSON Example​

Operations​

Read​

Search​

Search Parameters​

Create​

Update​

Examples​

Request Examples​

Response Examples​

Successful Search Response​

Individual Schedule Response​

Empty Result Set​

Create​

Update​

Integration Patterns​

Common Workflows​

Related Resources​

Error Handling​

Schedule-Specific Error Scenarios​

Troubleshooting Tips​

Supported Profiles​

Overview

Purpose

Use Cases

Relationships

Resource Schema

Key Fields

JSON Example

Operations

Read

Search

Search Parameters

Create

Update

Examples

Request Examples

Response Examples

Successful Search Response

Individual Schedule Response

Empty Result Set

Create

Update

Integration Patterns

Common Workflows

Related Resources

Error Handling

Schedule-Specific Error Scenarios

Troubleshooting Tips

Supported Profiles