The Python SDK for the haau3 platform API, as typed calls:
- Scheduling: open appointment slots from many SMART Scheduling Links publishers, in one search.
- Medical Benefits: Medicare Advantage and ACA Marketplace plans as FHIR
InsurancePlan, searchable by state or county, and which providers are in a plan's network. - MedList: one reconciled medication list from one patient's FHIR medication records.
On the same key and FHIR base: RxNorm, LOINC and ICD-10-CM lookups, value sets and code validation (Terminology), practitioners and organizations from CMS's National Provider Directory (Provider directory), and standard FHIR Questionnaires such as the PHQ-9.
The haau3 platform API is in preview: it may change as we build, usually to add features or improve performance.
Also for TypeScript: @haau3/sdk, and for Go:
github.com/haau3/haau3-go.
pip install haau3Python 3.10 or newer. The SDK runs on a server only: it refuses to start in a browser (Pyodide), where your API key would be public.
Create an API key on platform.haau3.com, then set it as
HAAU3_API_KEY or pass it as api_key. To try the API with no key first, call the Sandbox (see
"The Sandbox" below).
Or make the key from your project's folder with the
haau3 command line (Node 22 or newer): npx haau3 login, then
npx haau3 keys create, which writes it to the project's env file and never shows it. Load that
file when the program starts, such as with python-dotenv's
load_dotenv().
from haau3 import Haau3
client = Haau3() # reads HAAU3_API_KEYMake one client and reuse it: it holds a pool of connections, and is safe to share between threads.
import json
# Open appointment slots, here in Cambridge.
slots = client.search_slots(city="Cambridge", state="MA", limit=1)["slots"]
print(json.dumps(slots[0], indent=2) if slots else "No open slots matched.")An answer is the JSON the API sent, as plain dicts and lists, so it goes into json.dumps, a
DataFrame or a database as it is. Each is typed with a TypedDict, so a type checker and your
editor know every key: FHIR answers with HL7's R4 types (haau3.fhir), the other services' answers
with the API's own (haau3.types). FHIR elements are optional, so read them with .get().
AsyncHaau3 has the same methods, awaited. It runs on asyncio and on trio.
from haau3 import AsyncHaau3
async_client = AsyncHaau3()
plan = await async_client.read_insurance_plan("H2406-013-000")Make one per event loop and reuse it, as FastAPI's lifespan does (see "Using it with FastAPI, Django and Flask"); it must not outlive its event loop.
# Scheduling: open appointment slots, here in Boston.
found = client.search_slots(city="Boston", state="MA", limit=10)
print(found["total"], len(found["slots"]))
# Provider directory: a practitioner by NPI, from CMS's National Provider Directory.
practitioners = client.search_practitioner(identifier="1093209884")
# Terminology: a LOINC code's display and properties.
glucose = client.code_system_lookup(system="http://loinc.org", code="2345-7")
# Questionnaires: a form by its id, such as the PHQ-9.
phq9 = client.read_questionnaire("44249-1")
# Medical Benefits: a Medicare Advantage or ACA Marketplace plan, and which providers are in its network.
plan = client.read_insurance_plan("H2406-013-000")
network = client.check_insurance_plan_network("H3359-038-000", npi=["1518929058"])
# Pharmacy Benefits: what a medication would cost, as the CARIN pharmacy benefit check, from a FHIR
# message Bundle. It is not yet open to customers.
checked = client.process_message(message)
# MedList: one reconciled medication list from one patient's FHIR medication records. It receives
# patient data, so send it only under an executed agreement. Test data labelled as such works on every
# plan, and mark_as_test_data labels a request and every resource in it. Label only made-up data.
reconciled = client.reconcile_medications(records)
# Structured Sig: a prescription's free-text directions as a FHIR Dosage, each element coded where the
# words support it and a review flag on anything to check. Send the directions, never a patient.
from haau3 import structure_dosage_request
structured = client.structure_dosage(structure_dosage_request("Take 1 tablet by mouth twice daily"))
# The Sandbox: the same calls, answered with fixed answers and a test insurer's synthetic data. A test
# key sends every call there (see "The Sandbox" below). Its pharmacy benefit check answers its test
# members only (https://docs.haau3.com/sandbox/example-health-plan).
sandbox = Haau3(api_key=test_key)
sandbox_checked = sandbox.process_message(sandbox_message)Every method, grouped by service, with its request and a link to its page on docs.haau3.com, is in
api.md. Each is named by its operationId
in snake_case, and so is each query parameter: name:contains is name_contains, _count is
count, serviceTypeCode is service_type_code. Each method's docstring gives both names.
The Sandbox, https://sandbox.haau3.com, is the API's environment to build and test against. It
serves production's operations at production's paths: each answers its documented example request
with a fixed answer, and the pharmacy benefit check is answered by a test insurer with synthetic
data. See docs.haau3.com for what it answers and its limits.
Your key's mode picks where the client sends every call. A test key (haau3_sk_test_…) goes to
the Sandbox, and a live key (haau3_sk_live_…) to production, so HAAU3_API_KEY alone moves an app
from one to the other. The Sandbox also answers with no key at all. With HAAU3_API_KEY unset, name
it as the environment:
sandbox = Haau3(environment="sandbox") # or set HAAU3_ENVIRONMENT=sandbox
statement = sandbox.fhir_metadata()
print(sandbox.environment, sandbox.base_url) # sandbox https://sandbox.haau3.comA key made before test and live keys goes to production, as a live key does. These are refused when
the client is made, before anything is sent. The error says where the key came from, and its code
says which it is:
- a test key with
environment="production"(test-key-outside-sandbox); - a live key, or one made before test and live keys, with
"sandbox"or with the Sandbox's address as thebase_url(live-key-in-sandbox,older-key-in-sandbox); - no key without the Sandbox named (
no-api-key); - an
environmentthat abase_urlon the other environment's address contradicts (environment-conflicts-with-base-url); - a key with anything before its
haau3_sk_prefix, such as the quotes an env file kept (api-key-not-alone).
environment and base_url on the client say what it resolved.
sandbox_process_message and sandbox_metadata, the Sandbox's first address at
/v1/sandbox/fhir/r4, are deprecated: call process_message and fhir_metadata instead. Until the
address goes, a client sending to the Sandbox's own host sends them to those operations there. The
raw request() sends a path as it is given, so a first-address path sent on a test key goes to the
Sandbox's host, which does not serve it.
An agent can read the docs directly:
- docs.haau3.com/llms.txt lists every docs page as Markdown.
- docs.haau3.com/skill.md is an
Agent Skill that says what the platform does and how to call
it.
npx skills add https://docs.haau3.comadds it to your project's coding agents. https://docs.haau3.com/mcpis an MCP server that searches the docs. To add it:- Claude Code:
claude mcp add --transport http haau3 https://docs.haau3.com/mcp - Codex:
codex mcp add haau3 --url https://docs.haau3.com/mcp - Cursor, in
.cursor/mcp.json:{ "mcpServers": { "haau3": { "url": "https://docs.haau3.com/mcp" } } } - VS Code:
code --add-mcp '{"name":"haau3","type":"http","url":"https://docs.haau3.com/mcp"}'
- Claude Code:
The haau3 command line lets an agent act without ever seeing
a key. npx haau3 doctor --json checks the project's setup, and npx haau3 test --json makes one
call to each service, in the Sandbox when there is no key. npx haau3 login, then
npx haau3 keys create, puts a key in the project's env file after a person approves in the
browser.
| Option | Default | |
|---|---|---|
api_key |
os.environ["HAAU3_API_KEY"] |
Your platform API key. A test key calls the Sandbox, a live key production. |
environment |
os.environ["HAAU3_ENVIRONMENT"], then the key's mode |
"production" or "sandbox". Name "sandbox" to call it with no key. |
base_url |
os.environ["HAAU3_BASE_URL"], then the environment's address |
Where the API is, for a stand-in or a proxy. The API key is sent there only. |
timeout |
65.0 |
Seconds one attempt may take. |
max_retries |
1 |
Retries after a timeout, a network failure, a 429 or a 5xx. |
http_client |
a new httpx2.Client (httpx2.AsyncClient for AsyncHaau3) |
Your own, for a proxy, certificates or connection limits. |
app_info |
none | Your app's name, version and URL, sent in the User-Agent after the SDK's own. |
Each call takes timeout, max_retries, correlation_id and extra_headers as keywords, for
that call only:
client.search_slots(state="MA", timeout=10, max_retries=0)An operation that declares a header of its own takes it as one more keyword, named from the header
and typed from the spec. process_message takes payer_authorization, sent as
Payer-Authorization: a member's own authorization at their insurer, Bearer and the access token
your app got from the member's login there. The SDK checks it against the form the API takes before
sending, refuses one the API would not take without repeating it, and holds it where nothing prints
it, a traceback's local variables included.
checked = client.process_message(message, payer_authorization=f"Bearer {access_token}")http_client passes anything httpx2 takes: a proxy,
certificates, limits, event hooks, a transport. The SDK's own method, URL, headers, body and
timeout always win, it never follows a redirect, and it never closes a client you pass.
import httpx2
proxied = Haau3(http_client=httpx2.Client(proxy="http://proxy.internal:8080"))httpx2 checks the API's certificate against your operating system's trust store, or against the
file SSL_CERT_FILE names. In a slim container with no CA certificates, install them, set
SSL_CERT_FILE, or pass http_client=httpx2.Client(verify=ssl.create_default_context(cafile=...)).
app_info names your app in the User-Agent, after the SDK's own, when you build a library, a plugin
or a command line on the SDK. It takes a name, and a version and a url if you have them, and
every request the client sends carries them:
named = Haau3(app_info={"name": "my-plugin", "version": "1.2.0"})
# User-Agent: haau3-python/<version> (python 3.13; httpx2 <version>) my-plugin/1.2.0A name and a version each take letters, digits, -, ., _ and the other characters RFC 9110
allows in a User-Agent product, with no space or slash. A url is an http or https URL, sent in
parentheses after them. Anything else is refused when the client is made, before a request is sent.
A user-agent in a call's extra_headers replaces the whole User-Agent, the SDK's part included.
AppInfo types the dict.
A retry waits a short, growing interval, or what the API's Retry-After header says when that is
60 seconds or less. A longer Retry-After fails at once, carrying it. Nothing is cached: every call
asks the API.
An async attempt ends at its timeout exactly. A sync attempt's timeout bounds connecting and each read, and is checked between parts of the answer, so one read that stalls can run past it by up to the timeout again.
Every error is a Haau3Error, with the request_id the API answered with. There are four kinds:
from haau3 import AuthError, ForbiddenError, NoAnswerError, RefusedError
try:
client.read_insurance_plan(plan_id)
except RefusedError as error:
print(error.status) # 400, 404, 410 and so on
print(error.code) # why, when the API names it: "not-the-example" from the Sandbox
print(error.outcome) # the OperationOutcome; Scheduling's errors carry `problem`
except NoAnswerError as error:
print(error.reason) # "timeout", "network", "rate-limited", "unavailable", "server-error" or "unreadable"
print(error.retry_after) # seconds, when the API said
print(error.detail) # for a timeout or a network failure: what failed, such as "ConnectError: Connection refused"
except ForbiddenError as error:
# 403: the key was accepted, and it may not make this request. Why, when the API names it:
# "test-key-outside-sandbox", "live-key-in-sandbox", "phi-agreement-required" or "not-open-to-customers"
print(error.code)
except AuthError:
pass # 401: the key was missing, unknown or revokedA 403 is a ForbiddenError, never an AuthError: the key was accepted, so there is nothing to
rotate. Its code says why when the API names it, and its message says the same in words. A test
key works only in the Sandbox (test-key-outside-sandbox: send a live key), and a live key does not
work there (live-key-in-sandbox: send a test key). The client sends each key to its own
environment, so you meet these with a base_url of your own, or by calling the deprecated
sandbox_… methods with a live key. phi-agreement-required means the organization
may not send patient data, and not every resource in the request is labelled as test data:
mark_as_test_data labels made-up data. not-open-to-customers means the operation is not yet
open to customers: an expected answer, not a fault in the request. Without a code, the body says what
the organization may not do.
A RefusedError's code names the API's reason when it gives one: not-the-example from the
Sandbox, which answers each operation's documented example only and refuses any other request.
A client that cannot be made raises a Haau3Error before anything is sent, with a code to branch on,
which the ClientErrorCode type lists. The message says the same for a person and names where the
value came from, the keyword or the variable:
from haau3 import Haau3, Haau3Error
try:
configured = Haau3()
except Haau3Error as error:
if error.code == "no-api-key":
pass # set HAAU3_API_KEY, or name the Sandbox to call it with no keyThe codes are no-api-key, invalid-api-key, api-key-not-alone, test-key-outside-sandbox,
live-key-in-sandbox, older-key-in-sandbox, invalid-environment, invalid-base-url,
environment-conflicts-with-base-url, invalid-app-info, invalid-http-client and in-browser. The
two the API also answers with keep the API's names.
When HAAU3_API_KEY has no value but .env.local or .env in the current folder sets it, the
no-api-key message names that file and says how to load it. The SDK looks there only when it has no
key from HAAU3_API_KEY, opens only a regular file, and never keeps or shows the value.
No answer is never reported as an empty result, and an empty result is never an error. Every error
the API answered carries attempts, duration_ms and reason_phrase too.
An error's message never includes the body the API answered with, and the body (outcome or
problem) is never printed when the error is: not by str(), repr() or a traceback, and not
among a traceback's local variables, which some error reporters record. A request body you sent is
held the same way. An error pickles, for Celery or multiprocessing, with every field but its body.
A FHIR answer is checked against the resource types its operation answers with. Anything else, a
Bundle where an InsurancePlan was asked for, say, is a NoAnswerError with reason
"unreadable". The check is of the resource type, not of every element inside it: those are typed
as FHIR R4 declares them, and the SDK does not validate each one.
error.to_dict() gives an error as a dict that is safe to log: its name, its message and the fields
above that are set, and never the body or the cause.
import logging
from haau3 import Haau3Error
try:
client.read_insurance_plan(plan_id)
except Haau3Error as error:
logging.getLogger(__name__).warning("the plan read failed", extra={"haau3": error.to_dict()})client.with_response has every method again, each returning a Response: the answer as data,
with the request id and timing that came with it, in the same names request() uses.
response = client.with_response.read_insurance_plan(plan_id)
print(response.data.get("name"), response.request_id, response.duration_ms, response.attempts)It carries status and reason_phrase too: the answer's own text, or the standard one ("OK") when
it came with none, as HTTP/2 answers do.
Quote the request_id when you ask for help: it finds the request in the API's own logs.
To find a request by an id of your own, such as your job's or your trace's, pass it as
correlation_id. It must be a UUID, which is all the API keeps; anything else is refused before it
is sent. The API keeps it with its record of the request, and it comes back on the answer and on
every error the API answered:
response = client.with_response.read_insurance_plan(plan_id, correlation_id=job_id)
print(response.correlation_id)pages() yields a FHIR search's first page and every page after it, following each next link on
the client's own host:
first = client.search_insurance_plan(coverage_area_state="NC")
for page in client.pages(first):
for entry in page.get("entry", []):
resource = entry.get("resource")
if resource is not None:
print(resource.get("id"))resources() yields every resource the search found, across every page:
for resource in client.resources(first):
if resource["resourceType"] == "InsurancePlan":
print(resource.get("name"))It yields each entry whose search mode is match, or says none. A resource an _include or
_revinclude brought, and a search's own OperationOutcome, are not among them; pages() gives
every entry. From async code, async for page in async_client.pages(first) and async for resource in async_client.resources(first). Scheduling's searches page with limit and offset, and answer
with a total.
FHIR operations answer with a Parameters resource whose parts are named: $lookup's display and
property parts, $structure-dosage's dosage part. parameters() gives every part with a name and
parameter() the one, both with no request, as FHIR's own SDKs read one (Firely's Get and
GetSingleValue, HAPI's ParametersUtil). A part holds its value in the value[x] its operation
names. parameter() raises when two parts share the name.
lookup = client.code_system_lookup(system="http://loinc.org", code="2345-7")
display = client.parameter(lookup, "display")
print(display.get("valueString") if display else None)Each is a client method and a plain function of the package, haau3.parameters(),
haau3.parameter() and haau3.review_flags(), so an answer you stored can be read with no client
and no key.
lookup_result() reads a $lookup answer, typed: the code, its system and version, its display,
whether it is abstract (not for use, such as an ICD-10-CM header), every designation and every
property. A property's type names the FHIR type of its value, so checking it narrows the value.
designations() finds a code's names by use and language: a use by its system and code together, a
language as RFC 4647 matches one, so en finds en-US. ICD-10-CM's short title is its SYNONYM_USE
designation, where it differs from the display, and every code system the API holds names the display
again with PREFERRED_FOR_LANGUAGE_USE.
from haau3 import SYNONYM_USE, designations
icd_answer = client.code_system_lookup(system="http://hl7.org/fhir/sid/icd-10-cm", code="E08.37X1")
icd_lookup = client.lookup_result(icd_answer)
print(icd_lookup.display, icd_lookup.abstract)
short_titles = designations(icd_lookup, use=SYNONYM_USE, language="en")
print(short_titles[0].value if short_titles else None)
for prop in icd_lookup.properties:
if prop.type == "boolean":
print(prop.code, prop.value)validation_result() reads a $validate-code answer, from a code system or a value set: result,
display and message. A display that does not match answers result False with the code's own
display beside it, which means the code is valid and only the label differs.
check = client.validation_result(
client.code_system_validate_code(url="http://loinc.org", code="2345-7", display="Glucose")
)
if not check.result:
print(check.message, check.display)A part either reader does not know is kept, as the answer gave it, in the other tuple of the level it
was found at, and a part FHIR allows once that comes twice raises. Each is a client method and a plain
function of the package, haau3.lookup_result(), haau3.validation_result() and
haau3.designations(), so an answer you stored can be read with no client.
structure_dosage_request() builds the request $structure-dosage takes from the directions and,
optionally, the medication's codings, RxNorm or NDC, as a FHIR CodeableConcept. RXNORM_SYSTEM and
NDC_SYSTEM are their code systems. It is a plain function, so it builds a batch entry too
(calls.structure_dosage(structure_dosage_request(text))).
The answer is one dosage part, a FHIR Dosage, with a review flag on anything a person should
check. review_flags() reads each flag's code, display and the words of the directions it is about,
and the versions the Dosage names:
from haau3 import RXNORM_SYSTEM, review_flags, structure_dosage_request
structured_answer = client.structure_dosage(
structure_dosage_request(
"Take 1 tablet by mouth daily",
medication={"coding": [{"system": RXNORM_SYSTEM, "code": "311354"}]},
)
)
part = client.parameter(structured_answer, "dosage")
if part and "valueDosage" in part:
review = review_flags(part["valueDosage"])
for flag in review.flags:
print(flag.code, flag.display, flag.words)
print(review.engine_version, review.vocabulary_version, review.rxnorm_release)batch() sends several operations of the FHIR base as one request. Each entry comes from
haau3.calls, whose functions are called as the client's methods of the same name are, and gets its
own result, in the order given:
from haau3 import BatchOk, calls
plan_result, counties_result = client.batch(
calls.read_insurance_plan("H2406-013-000"),
calls.list_insurance_plan_counties(state="NC"),
)
if isinstance(plan_result, BatchOk):
print(plan_result.data.get("name")) # an InsurancePlan
else:
print(plan_result.error) # a RefusedError or a NoAnswerError, as read_insurance_plan alone would have raisedA result is a BatchOk (data, status) or a BatchError (error), typed by position for up to
six entries; match result: case BatchOk(data=data): ... works too. Each also has ok, True or
False, which reads well in a log; isinstance and match are what tell a type checker which it
is. A list built in code works the same way:
lookups = client.batch(
*(calls.code_system_lookup(system="http://loinc.org", code=code, property="SHORTNAME") for code in codes)
)Each entry is checked as the call alone is, and fails alone while the others answer. An entry that
fails is not retried. The batch itself is retried, and raises, as any call does, and
client.with_response.batch(...) gives its request id. The API takes up to 100 entries in up to 1
MiB and gives a batch 60 seconds, so send a longer list as several batches. Every operation on the
FHIR base can go in a batch except fhir_batch, process_message and reconcile_medications, which
the spec marks x-haau3-batchable: false.
To send a batch Bundle you built yourself, fhir_batch() takes it and returns the
batch-response as it is.
get() and post() call an operation by its path: one this version of the SDK has no method for
yet, or one a tool found in the spec. Each takes the path as the spec writes it, a value for each
{name} in path_params, the query, the body (for post()) and the FHIR types the answer may
be in expects, beside every per-call option. They raise the same errors as every operation's own
method, and with_response.get() and with_response.post() return the request id and timing too:
practitioner = client.get(
"/v1/fhir/r4/Practitioner/{id}",
path_params={"id": "Practitioner-1093209884"},
expects=["Practitioner"],
)
metadata = client.with_response.get("/v1/fhir/r4/metadata", expects=["CapabilityStatement"])
print(metadata.request_id)Each value is encoded into the path, and an error's message names the path as you wrote it, never a
value. A {name} with no value, or a value with no {name}, is refused before anything is sent.
request() sends a request as you give it and returns what the API answered, whatever the status,
with its headers, request id, attempts and duration:
raw = client.request("GET", "/v1/scheduling/publishers")
print(raw.status, raw.reason_phrase, raw.request_id)Each of these is a complete, tested example in examples/:
- FastAPI (fastapi_app.py):
an
AsyncHaau3made in the app's lifespan, handed to each route by a dependency, and closed when the app stops. - Django (django_view.py):
one
Haau3for the whole process, shared by every request and thread. - Flask (flask_app.py):
one
Haau3on the app. Flask runs each async view in an event loop of its own, which anAsyncHaau3must not outlive, so async views use the sync client too. - A script (plans_to_csv.py): every page of a plan search, written to CSV, with the client as a context manager.
Pass an httpx2.Client with a MockTransport, and your code calls the SDK as it always does:
import httpx2
from haau3 import Haau3
def answer(request: httpx2.Request) -> httpx2.Response:
return httpx2.Response(200, json={"resourceType": "InsurancePlan", "id": "H2406-013-000"})
test_client = Haau3(api_key="test", http_client=httpx2.Client(transport=httpx2.MockTransport(answer)))
assert test_client.read_insurance_plan("H2406-013-000").get("id") == "H2406-013-000"To run code you have not changed against a stand-in API of your own, set HAAU3_BASE_URL to its
address: a client built with no base_url sends there, and nowhere else.
The SDK is 0.y.z while the API is in preview: a minor release may change what a method takes or
answers, and a patch release never does. CHANGELOG.md
lists every release, and a release that takes a new version of the API's spec names that version;
haau3.SPEC_VERSION is the one a release was generated from.