---
title: Recipes
description: End-to-end integration workflows for the Huli Public API — each one ships a working result against the v1 FHIR R4 surface.
nav: Recipes
order: 0
version: v1
source: handwritten
updated: 2026-07-08
---

# Recipes

Opinionated, end-to-end workflows. Each recipe ships a working result against the v1
surface — bearer auth, the four read-write FHIR R4 resources (Patient, Appointment,
Encounter, Observation), and the `huli` CLI. Code samples are shown in cURL,
TypeScript, Python, Java, and Go; every one runs as-is.

## What do you want to build?

<UseCaseGrid>

<UseCaseCard icon="user-plus" title="Register a patient" description="Create and dedupe a Patient record." chip="POST /Patient" href="/v1/recipes/registering-a-patient" />

<UseCaseCard icon="calendar-clock" title="Book an appointment" description="Availability → booked, end to end." chip="POST /Appointment" href="/v1/recipes/booking-an-appointment" />

<UseCaseCard icon="flask" title="Send results from the lab" description="Push laboratory results into the chart as Observations." chip="POST /Observation" href="/v1/recipes/posting-lab-observations-lis" />

<UseCaseCard icon="sync" title="Sync a daily patient list" description="Pull each day's patients and appointments with the Huli CLI." chip="huli fhir patient search" href="/v1/recipes/daily-roster-sync-cli" />

<UseCaseCard icon="lock" title="Wire a read-only partner" description="Give an analytics or reporting tool least-privilege read access." chip="system/Patient.rs" href="/v1/recipes/wiring-a-read-only-partner" />

<UseCaseCard icon="webhook" title="Receive webhooks" description="React to appointments and clinical events as they happen." chip="POST /webhooks" href="/v1/recipes/receiving-webhooks" />

</UseCaseGrid>

## v1 recipes

- **[Sandbox quickstart](/v1/recipes/sandbox-quickstart)** — get a sandbox organization pre-seeded with fake FHIR data from a Huli org admin, receive the bearer credential through a one-time share link, and make your first call. Five minutes from link to a `200`.
- **[Run your first authenticated Patient search](/v1/recipes/getting-started-patient-search)** — bearer token + `system/Patient.rs`, the canonical first request. Five minutes from key to `searchset`.
- **[Registering a patient](/v1/recipes/registering-a-patient)** — discover the NOM-024 / MX address codes via the terminology ValueSets, then `POST` a Patient with CURP/RFC identifiers and the second-lastname extension using `system/Patient.cru`.
- **[Booking an appointment end-to-end](/v1/recipes/booking-an-appointment)** — discover a service, practitioner, room, and free slot with `system/Appointment.cru` + `system/Practitioner.rs`, then `POST` the Appointment past its booking preconditions — including the `specialty` selection a multi-specialty service requires.
- **[Scheduling an administrative meeting](/v1/recipes/scheduling-an-administrative-meeting)** — book an internal meeting with no patient: a required title, optional all-day flag, and external email invitees, against a service whose appointment type is `administrative`.
- **[Creating a clinical encounter](/v1/recipes/creating-an-encounter)** — discover the practitioner participant, then `POST` an Encounter for an existing patient with `system/Encounter.cru` + `system/Patient.rs` + `system/Practitioner.rs`.
- **[Writing and amending a clinical note](/v1/recipes/writing-a-clinical-note)** — create the LOINC-sectioned `Composition` projection of a visit and amend it with `If-Match` optimistic concurrency, using the BAA-gated `system/Composition.cru`.
- **[Uploading a document](/v1/recipes/uploading-a-document)** — attach a PDF, scan, or image as a `DocumentReference` (multipart `$upload` or inline base64) and read it back via a 30-minute signed URL, using the BAA-gated `system/DocumentReference.cru`.
- **[Fetching a patient's full record](/v1/recipes/fetching-a-patient-record)** — pull a patient's encounters, observations, notes, documents, medications, and orders in one scope-filtered `Patient/$everything` Bundle.
- **[Wire a read-only partner](/v1/recipes/wiring-a-read-only-partner)** — consume Appointment + Encounter read-only with `system/Appointment.rs` + `system/Encounter.rs`, resolving the Practitioner/Organization references they point at.
- **[Sync a daily patient list with the huli CLI](/v1/recipes/daily-roster-sync-cli)** — cron-safe, restart-idempotent Patient + Appointment pagination driven by the CLI.
- **[Send lab results to the chart](/v1/recipes/posting-lab-observations-lis)** — create Observations with required LOINC codes and UCUM units, with reference-range handling.
- **[Creating and sharing an API key as a clinic admin](/v1/recipes/creating-and-sharing-an-api-key)** — the Practice Settings flow to mint, scope, reveal, share, and rotate an admin bearer key.
- **[Choosing a CLI authentication path](/v1/recipes/cli-authentication-paths)** — interactive OAuth vs M2M (`huli auth setup`) vs a one-off bearer token; when to use which.
- **[Debugging a failed FHIR search](/v1/recipes/debugging-a-failed-fhir-search)** — read the `OperationOutcome`, map the common failures, and trace a correlation id to its audit record.
- **[Receive webhooks](/v1/recipes/receiving-webhooks)** — register a `rest-hook` Subscription with `system/Subscription.crud`, verify the HMAC signature on every delivery, dedupe on the event id, and recover missed events with `$replay`.