for Developers

Schedule (FHIR R4)

FHIR You're viewing the FHIR R4 reference.

FHIR R4 Schedule resource.

This reference is generated from the canonical Huli Public API OpenAPI specification and the server's FHIR R4 CapabilityStatement — do not edit it directly.

FHIR R4 Specification

Official spec: Schedule — HL7 FHIR R4

Supported Interactions

  • read — Read a single resource by ID (GET /fhir/R4/{Resource}/{id})
  • search-type — Search resources with query parameters (GET /fhir/R4/{Resource}?...)

Scopes

Scopes are shared across FHIR releases — the same system/Schedule.* scope grants Schedule access on both /fhir/R4 and /fhir/R5.

Search Parameters

ParameterTypeNotes
_idtokenExact match. For identifiers use `system
actorreferenceResource reference — supply the UUID of the referenced resource.
service-typetokenExact match. For identifiers use `system
_countnumberInteger. For _count: default 20, max 100.
_offsetnumberInteger. For _count: default 20, max 100.

Endpoints

Read Schedule

Retrieve a single Schedule resource by its ID. This is a read-only discovery resource, gated by system/Appointment.rs because it supports appointment booking.

GET/fhir/R4/Schedule/{id}

Required scope: system/Appointment.rs

Response — 200

{
  "resourceType": "Schedule",
  "id": "110e8400-e29b-41d4-a716-446655440100",
  "active": true,
  "actor": [
    {
      "reference": "PractitionerRole/ff0e8400-e29b-41d4-a716-446655440090"
    }
  ]
}

Code Samples

TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/Appointment.rs" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/R4/Schedule/${RESOURCE_ID} \
  -H "Authorization: Bearer ${TOKEN}"

const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/Schedule/${id}`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
    },

  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();

import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}

resp = requests.get(
    f"https://api.huli.ai/fhir/R4/Schedule/{resource_id}",
    headers=headers,
)
resp.raise_for_status()
print(resp.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class getScheduleExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String resourceId = "RESOURCE_ID";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/Schedule/" + resourceId))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}

import (
    "fmt"
    "net/http"
    "os"
)

func getScheduleExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/Schedule/"+resourceID+"", nil)
    req.Header.Set("Authorization", "Bearer "+token)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}

Errors

CodeStatusDescription
HPB-00106401Authentication failed
HPB-00104403Insufficient scope
HPB-00102404Resource not found
HPB-00105429Rate limit exceeded

Search Schedule

Search Schedule resources. Results are returned as a FHIR searchset Bundle. This is a read-only discovery resource, gated by system/Appointment.rs because it supports appointment booking. Exactly one of _id, actor, or service-type is required; supplying more than one is rejected.

GET/fhir/R4/Schedule

Required scope: system/Appointment.rs

Query Parameters

nametyperequireddescription
_idstringoptionalSchedule resource ID (UUID).
actorstringoptionalFilter by the actor the schedule belongs to. The actor is the PractitionerRole (or resource) ID — accepts a UUID or a typed reference such as `PractitionerRole/<uuid>`.
service-typestringoptionalFilter by the org service the schedule is configured to deliver, to enumerate the practitioner/room combinations that satisfy it for booking . This is the FHIR-standard `service-type` token param targeting `Schedule.serviceType`. The value is the org-service code published as `HealthcareService.type[0].coding[0].code` — accepts a bare UUID or the `system|code` token form (the system, when present, must be the org-service CodeSystem). Each matching schedule exposes a `PractitionerRole` + `Location` actor pair; a schedule with no service restriction matches every `service-type` query for a live org service. A `service-type` that is not a live service in the caller's org returns an empty bundle.
_countintegeroptionalNumber of results per page (default: 20, max: 100).
_offsetintegeroptionalNumber of results to skip (offset-based pagination).

Response — 200

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "Schedule/110e8400-e29b-41d4-a716-446655440100",
      "resource": {
        "resourceType": "Schedule",
        "id": "110e8400-e29b-41d4-a716-446655440100",
        "active": true,
        "actor": [
          {
            "reference": "PractitionerRole/ff0e8400-e29b-41d4-a716-446655440090"
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Code Samples

TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/Appointment.rs" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/R4/Schedule \
  -H "Authorization: Bearer ${TOKEN}"

const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/Schedule`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
    },

  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();

import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}

resp = requests.get(
    f"https://api.huli.ai/fhir/R4/Schedule",
    headers=headers,
)
resp.raise_for_status()
print(resp.json())

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class searchScheduleExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/Schedule"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}

import (
    "fmt"
    "net/http"
    "os"
)

func searchScheduleExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/Schedule", nil)
    req.Header.Set("Authorization", "Bearer "+token)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}

Errors

CodeStatusDescription
HPB-00106401Authentication failed
HPB-00104403Insufficient scope
HPB-00105429Rate limit exceeded