Encounter (FHIR R4)

FHIR You're viewing the FHIR R4 reference.

An interaction between a patient and healthcare provider for the purpose of providing healthcare service. Maps to HuliPractice clinical encounters (consultations).

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: Encounter — 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}?...)
create — Create a new resource (POST /fhir/R4/{Resource})
update — Update an existing resource (PUT /fhir/R4/{Resource}/{id})

Scopes

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

system/Encounter.rs — see scope reference
system/Encounter.cru — see scope reference

Search Parameters

Parameter	Type	Notes
`_id`	token	Exact match. For identifiers use `system
`patient`	reference	Resource reference — supply the UUID of the referenced resource.
`practitioner`	reference	Resource reference — supply the UUID of the referenced resource.
`date`	date	Supports FHIR date prefixes: `eq`, `ne`, `gt`, `ge`, `lt`, `le`. Format: `[prefix]YYYY-MM-DD`.
`status`	token	Exact match. For identifiers use `system
`class`	token	Exact match. For identifiers use `system
`_count`	number	Integer. For `_count`: default 20, max 100.
`_cursor`	string	Case-insensitive partial match.

Endpoints

Read Encounter

Retrieve a single Encounter resource by its ID.

GET/fhir/R4/Encounter/{id}

Required scope: system/Encounter.rs

Response — 200

{
  "resourceType": "Encounter",
  "id": "990e8400-e29b-41d4-a716-446655440030",
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "subject": {
    "reference": "Patient/550e8400-e29b-41d4-a716-446655440001",
    "display": "Maria Garcia"
  },
  "participant": [
    {
      "individual": {
        "reference": "Practitioner/880e8400-e29b-41d4-a716-446655440020",
        "display": "Dr. Rodriguez"
      }
    }
  ],
  "period": {
    "start": "2026-05-20T10:00:00Z",
    "end": "2026-05-20T10:45:00Z"
  }
}

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/Encounter.rs" \
  | jq -r .access_token)

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

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

const response = await fetch(
  `https://api.huli.ai/fhir/R4/Encounter/${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/Encounter/{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 getEncounterExample {
    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/Encounter/" + 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 getEncounterExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/Encounter/"+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

Code	Status	Description
HPB-00106	401	Authentication failed
HPB-00104	403	Insufficient scope
HPB-00102	404	Resource not found
HPB-00105	429	Rate limit exceeded

Update Encounter

Update an existing Encounter resource.

PUT/fhir/R4/Encounter/{id}

Required scope: system/Encounter.cru

Request Body

name	type	required	description
resourceType	string	required
id	string(uuid)	optional
meta	object	optional
status	string	required	Encounter status.
class	object	required
subject	object	optional
participant	array	optional
period	object	optional
reasonCode	array	optional
contained	array	optional	Contained supporting resources. The codec emits, by stable contained id: one `Condition` per diagnosis (`#condition-N`); a SOAP subjective/objective `ClinicalImpression` (`#subjective-objective-summary`); a diagnostic-impression `ClinicalImpression` (`#diagnostic-impression`, tagged LOINC 51848-0); and a follow-up-plan `CarePlan` (`#care-plan`).
diagnosis	array	optional	Encounter diagnoses, each referencing a contained `Condition`. `rank` 1 marks the primary diagnosis; ranks ≥ 2 mark secondaries (in stored order). An unspecified/legacy diagnosis emits no `rank`.

Request Example

{
  "resourceType": "Encounter",
  "id": "990e8400-e29b-41d4-a716-446655440030",
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "subject": {
    "reference": "Patient/550e8400-e29b-41d4-a716-446655440001"
  },
  "participant": [
    {
      "individual": {
        "reference": "Practitioner/880e8400-e29b-41d4-a716-446655440020"
      }
    }
  ],
  "period": {
    "start": "2026-05-20T10:00:00Z",
    "end": "2026-05-20T10:45:00Z"
  }
}

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/Encounter.cru" \
  | jq -r .access_token)

curl -X PUT https://api.huli.ai/fhir/R4/Encounter/${RESOURCE_ID} \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/fhir+json" \
  -d @resource.json

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

const response = await fetch(
  `https://api.huli.ai/fhir/R4/Encounter/${id}`,
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/fhir+json",
    },
    body: JSON.stringify(payload),
  }
);

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}", "Content-Type": "application/fhir+json"}

resp = requests.put(
    f"https://api.huli.ai/fhir/R4/Encounter/{resource_id}",
    headers=headers,
    json=payload,
)
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 updateEncounterExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String resourceId = "RESOURCE_ID";
        String payload = "{}"; // your serialized FHIR resource

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/Encounter/" + resourceId))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .header("Content-Type", "application/fhir+json")
        .method("PUT", HttpRequest.BodyPublishers.ofString(payload))
        .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 updateEncounterExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("PUT", "https://api.huli.ai/fhir/R4/Encounter/"+resourceID+"", body)
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/fhir+json")
    // set req.Body to your serialized resource
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}

Errors

Code	Status	Description
HPB-00101	400	Validation error
HPB-00106	401	Authentication failed
HPB-00104	403	Insufficient scope
HPB-00102	404	Resource not found
HPB-00101	422	Unprocessable entity
HPB-00105	429	Rate limit exceeded

Search Encounters

Search for Encounter resources using FHIR search parameters.

GET/fhir/R4/Encounter

Required scope: system/Encounter.rs

Query Parameters

name	type	required	description
patient	string	optional	Patient reference (UUID).
date	string	optional	Encounter date. Supports FHIR date prefixes: `eq`, `ne`, `gt`, `ge`, `lt`, `le`.
status	string	optional	Encounter status: `planned`, `in-progress`, `finished`, `cancelled`.
class	string	optional	Encounter class code (e.g., `AMB`, `IMP`, `VR`).
_count	integer	optional	Number of results per page (default: 20, max: 100).
_cursor	string	optional	Opaque pagination cursor from the `next` link of a previous search result.

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/Encounter.rs" \
  | jq -r .access_token)

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

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

const response = await fetch(
  `https://api.huli.ai/fhir/R4/Encounter`,
  {
    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/Encounter",
    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 searchEncountersExample {
    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/Encounter"))
        .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 searchEncountersExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/Encounter", 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

Code	Status	Description
HPB-00106	401	Authentication failed
HPB-00104	403	Insufficient scope
HPB-00105	429	Rate limit exceeded

Create Encounter

Create a new Encounter resource. The server assigns the resource ID.

POST/fhir/R4/Encounter

Required scope: system/Encounter.cru

Request Body

name	type	required	description
resourceType	string	required
id	string(uuid)	optional
meta	object	optional
status	string	required	Encounter status.
class	object	required
subject	object	optional
participant	array	optional
period	object	optional
reasonCode	array	optional
contained	array	optional	Contained supporting resources. The codec emits, by stable contained id: one `Condition` per diagnosis (`#condition-N`); a SOAP subjective/objective `ClinicalImpression` (`#subjective-objective-summary`); a diagnostic-impression `ClinicalImpression` (`#diagnostic-impression`, tagged LOINC 51848-0); and a follow-up-plan `CarePlan` (`#care-plan`).
diagnosis	array	optional	Encounter diagnoses, each referencing a contained `Condition`. `rank` 1 marks the primary diagnosis; ranks ≥ 2 mark secondaries (in stored order). An unspecified/legacy diagnosis emits no `rank`.

Request Example

{
  "resourceType": "Encounter",
  "status": "planned",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  },
  "subject": {
    "reference": "Patient/550e8400-e29b-41d4-a716-446655440001"
  },
  "participant": [
    {
      "individual": {
        "reference": "Practitioner/880e8400-e29b-41d4-a716-446655440020"
      }
    }
  ],
  "period": {
    "start": "2026-06-10T08:00:00Z"
  }
}

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/Encounter.cru" \
  | jq -r .access_token)

curl -X POST https://api.huli.ai/fhir/R4/Encounter \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/fhir+json" \
  -d @encounter.json

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

const response = await fetch(
  `https://api.huli.ai/fhir/R4/Encounter`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/fhir+json",
    },
    body: JSON.stringify(payload),
  }
);

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}", "Content-Type": "application/fhir+json"}

resp = requests.post(
    f"https://api.huli.ai/fhir/R4/Encounter",
    headers=headers,
    json=payload,
)
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 createEncounterExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String payload = "{}"; // your serialized FHIR resource

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/Encounter"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .header("Content-Type", "application/fhir+json")
        .method("POST", HttpRequest.BodyPublishers.ofString(payload))
        .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 createEncounterExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("POST", "https://api.huli.ai/fhir/R4/Encounter", body)
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/fhir+json")
    // set req.Body to your serialized resource
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}

Errors

Code	Status	Description
HPB-00101	400	Validation error
HPB-00106	401	Authentication failed
HPB-00104	403	Insufficient scope
HPB-00101	422	Unprocessable entity
HPB-00105	429	Rate limit exceeded

Encounter (FHIR R4)

#FHIR R4 Specification

#Supported Interactions

#Scopes

#Search Parameters

#Endpoints

#Read Encounter

#Response — 200

#Code Samples

#Errors

#Update Encounter

#Request Body

#Request Example

#Code Samples

#Errors

#Search Encounters

#Query Parameters

#Code Samples

#Errors

#Create Encounter

#Request Body

#Request Example

#Code Samples

#Errors

FHIR R4 Specification

Supported Interactions

Scopes

Search Parameters

Endpoints

Read Encounter

Response — 200

Code Samples

Errors

Update Encounter

Request Body

Request Example

Code Samples

Errors

Search Encounters

Query Parameters

Code Samples

Errors

Create Encounter

Request Body

Request Example

Code Samples

Errors