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.

Search Parameters

ParameterTypeNotes
_idtokenExact match. For identifiers use `system
patientreferenceResource reference — supply the UUID of the referenced resource.
practitionerreferenceResource reference — supply the UUID of the referenced resource.
datedateSupports FHIR date prefixes: eq, ne, gt, ge, lt, le. Format: [prefix]YYYY-MM-DD.
statustokenExact match. For identifiers use `system
classtokenExact match. For identifiers use `system
_countnumberInteger. For _count: default 20, max 100.
_cursorstringCase-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

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

Update Encounter

Update an existing Encounter resource.

PUT/fhir/R4/Encounter/{id}

Required scope: system/Encounter.cru

Request Body

nametyperequireddescription
resourceTypestringrequired
idstring(uuid)optional
metaobjectoptional
statusstringrequiredEncounter status.
classobjectrequired
subjectobjectoptional
participantarrayoptional
periodobjectoptional
locationarrayoptionalThe location (consultorio) the encounter took place in, as a `Location/<id>` reference to one of the practitioner's locations. Required on create when the practitioner works at more than one location, unless the encounter is bound to an appointment that has a location — and then, if sent, it must be the appointment's location (422 `HPB-00150`); create-only — an update naming a different location, or adding one, is refused with 422. Absent on historical encounters that recorded none.
reasonCodearrayoptional
containedarrayoptionalContained 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`).
diagnosisarrayoptionalEncounter 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

CodeStatusDescription
HPB-00101400Validation error
HPB-00106401Authentication failed
HPB-00104403Insufficient scope
HPB-00102404Resource not found
HPB-00103409Conflict
HPB-00154409Possible duplicate pending at the clinic
HPB-00101422Unprocessable entity
HPB-00105429Rate limit exceeded

Search Encounters

Search for Encounter resources using FHIR search parameters.

GET/fhir/R4/Encounter

Required scope: system/Encounter.rs

Query Parameters

nametyperequireddescription
patientstringoptionalPatient reference (a bare id, `Patient/<id>`, or an absolute URL ending in `Patient/<id>`). Any other value, including a reference to another resource type, a versioned reference or a comma-separated list, is rejected with `400` (HPB-00101).
practitionerstringoptionalPractitioner reference (a bare id, `Practitioner/<id>`, or an absolute URL ending in `Practitioner/<id>`). Any other value, including a reference to another resource type, a versioned reference or a comma-separated list, is rejected with `400` (HPB-00101).
datestringoptionalEncounter date. Supports FHIR date prefixes: `eq`, `ne`, `gt`, `ge`, `lt`, `le`.
statusstringoptionalEncounter status: `planned`, `in-progress`, `finished`, `cancelled`.
classstringoptionalEncounter class code (e.g., `AMB`, `IMP`, `VR`).
_countintegeroptionalNumber of results per page (default: 20, max: 100).
_cursorstringoptionalOpaque 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

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

Create Encounter

Create a new Encounter resource. The server assigns the resource ID. Every encounter records the location (consultorio) it took place in. Send location[0].location as a Location/<id> reference to one of the practitioner's locations, listed on PractitionerRole.location (GET /fhir/R4/PractitionerRole?practitioner=<id>). When the encounter is bound to an appointment that has a location, the appointment's location is recorded; if location is sent as well, it must be that location. When the practitioner works at exactly one location it may be omitted and that location is recorded. Otherwise the create is refused with 422 HPB-00150; a practitioner with no location at all gets 422 HPB-00151. Under la normativa (the Mexican regulation) what counts is the practitioner's normativa configuration: a location configured for them is accepted, one that is not is refused with 403 HPB-00141. A later update cannot change the location, or add one to an encounter recorded without it.

POST/fhir/R4/Encounter

Required scope: system/Encounter.cru

Request Body

nametyperequireddescription
resourceTypestringrequired
idstring(uuid)optional
metaobjectoptional
statusstringrequiredEncounter status.
classobjectrequired
subjectobjectoptional
participantarrayoptional
periodobjectoptional
locationarrayoptionalThe location (consultorio) the encounter took place in, as a `Location/<id>` reference to one of the practitioner's locations. Required on create when the practitioner works at more than one location, unless the encounter is bound to an appointment that has a location — and then, if sent, it must be the appointment's location (422 `HPB-00150`); create-only — an update naming a different location, or adding one, is refused with 422. Absent on historical encounters that recorded none.
reasonCodearrayoptional
containedarrayoptionalContained 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`).
diagnosisarrayoptionalEncounter 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"
      }
    }
  ],
  "location": [
    {
      "location": {
        "reference": "Location/990e8400-e29b-41d4-a716-446655440030"
      }
    }
  ],
  "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

CodeStatusDescription
HPB-00101400Validation error
HPB-00106401Authentication failed
HPB-00104403Insufficient scope
HPB-00103409Conflict
HPB-00154409Possible duplicate pending at the clinic
HPB-00101422Unprocessable entity
HPB-00105429Rate limit exceeded