curl "https://api.haau3.com/v1/fhir/r4/HealthcareService?location=Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d&_count=2" \
-H "Authorization: Bearer $HAAU3_API_KEY"import { Haau3 } from "@haau3/sdk";
const haau3 = new Haau3(); // reads HAAU3_API_KEY
const bundle = await haau3.searchHealthcareService({
location: "Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d",
_count: 2,
});
console.log(bundle.entry?.length ?? 0);
from haau3 import Haau3
client = Haau3() # reads HAAU3_API_KEY
bundle = client.search_healthcare_service(location="Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d", count=2)
print(len(bundle.get("entry", [])))
package main
import (
"context"
"fmt"
"log"
"github.com/haau3/haau3-go"
)
func main() {
ctx := context.Background()
client, err := haau3.NewClient() // reads HAAU3_API_KEY
if err != nil {
log.Fatal(err)
}
bundle, err := client.SearchHealthcareService(ctx, haau3.SearchHealthcareServiceParams{Location: new("Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d"), Count: new(2)})
if err != nil {
log.Fatal(err)
}
fmt.Println(len(bundle.Entry))
}
{
"resourceType": "Bundle",
"type": "searchset",
"link": [
{
"relation": "self",
"url": "https://api.haau3.com/v1/fhir/r4/HealthcareService?location=Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d&_count=2"
}
],
"entry": [
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/HealthcareService/HealthcareService-0009bcae-631e-45c0-9d3c-5691acb4a05d",
"resource": {
"resourceType": "HealthcareService",
"id": "HealthcareService-0009bcae-631e-45c0-9d3c-5691acb4a05d",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T21:17:34.307230248Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-HealthcareService"
]
},
"extension": [
{
"url": "http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-network-reference",
"valueReference": {
"reference": "Organization/Organization-ea579d05-454e-4359-8751-900c940a599a"
}
}
],
"active": true,
"location": [
{
"reference": "Location/Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d"
}
]
},
"search": {
"mode": "match"
}
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}Find healthcare services and pharmacies
Search HealthcareService two ways.
The directory’s services, by location, or by network beside a location. The directory’s service records name a network and, for a few, a location; none names an organization, so organization is refused on this search rather than answered with nothing.
Pharmacies, modelled as NDH 2.0.0 models them: each match is a pharmacy service, with category pharm and its NUCC pharmacy codes as specialty, provided by an organization at a store. Start the search with service-category=pharm (every kind) or specialty (one kind or several, separated by commas). A pharmacy search needs location.address-state with location.address-postalcode or location.address-city, or one pharmacy’s organization or organization.identifier; name narrows it. Add _include=HealthcareService:organization and _include=HealthcareService:location to get each pharmacy’s organization (its NPI) and store (its address) in the same bundle.
Pharmacies are found in NPPES, CMS’s NPI Registry, until CMS’s National Provider Directory serves them. Each is found and served at its primary practice address. The organization keeps the directory’s own id (Organization-{NPI}) and reads back from the directory, where a pharmacy registered in the last few weeks can answer 404 until the directory’s next load. A pharmacy service’s and store’s ids are read back from NPPES, and change when the search moves to the directory. NPPES returns at most 1,200 records for one search, so a continuation past them is refused with a 422 that asks for a narrower search, rather than repeating a page or ending early. One store can bill under more than one NPI, and each is served as its own pharmacy.
curl "https://api.haau3.com/v1/fhir/r4/HealthcareService?location=Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d&_count=2" \
-H "Authorization: Bearer $HAAU3_API_KEY"import { Haau3 } from "@haau3/sdk";
const haau3 = new Haau3(); // reads HAAU3_API_KEY
const bundle = await haau3.searchHealthcareService({
location: "Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d",
_count: 2,
});
console.log(bundle.entry?.length ?? 0);
from haau3 import Haau3
client = Haau3() # reads HAAU3_API_KEY
bundle = client.search_healthcare_service(location="Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d", count=2)
print(len(bundle.get("entry", [])))
package main
import (
"context"
"fmt"
"log"
"github.com/haau3/haau3-go"
)
func main() {
ctx := context.Background()
client, err := haau3.NewClient() // reads HAAU3_API_KEY
if err != nil {
log.Fatal(err)
}
bundle, err := client.SearchHealthcareService(ctx, haau3.SearchHealthcareServiceParams{Location: new("Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d"), Count: new(2)})
if err != nil {
log.Fatal(err)
}
fmt.Println(len(bundle.Entry))
}
{
"resourceType": "Bundle",
"type": "searchset",
"link": [
{
"relation": "self",
"url": "https://api.haau3.com/v1/fhir/r4/HealthcareService?location=Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d&_count=2"
}
],
"entry": [
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/HealthcareService/HealthcareService-0009bcae-631e-45c0-9d3c-5691acb4a05d",
"resource": {
"resourceType": "HealthcareService",
"id": "HealthcareService-0009bcae-631e-45c0-9d3c-5691acb4a05d",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T21:17:34.307230248Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-HealthcareService"
]
},
"extension": [
{
"url": "http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-network-reference",
"valueReference": {
"reference": "Organization/Organization-ea579d05-454e-4359-8751-900c940a599a"
}
}
],
"active": true,
"location": [
{
"reference": "Location/Location-ba334cb2-a0f9-4147-ab31-1c5af4ab9a4d"
}
]
},
"search": {
"mode": "match"
}
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "fatal",
"code": "<string>",
"details": {
"text": "<string>"
},
"diagnostics": "<string>",
"expression": [
"<string>"
]
}
]
}Authorizations
Your platform API key (haau3_sk_…), sent as Authorization: Bearer <key>.
Headers
An id of your own for this request, as a UUID. It comes back in the X-Correlation-Id header and is kept with haau3's record of the request. Any value that is not a UUID is ignored. See https://docs.haau3.com/errors#request-ids.
Query Parameters
The services offered at one location. Give a Location id, Location/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256The services the directory lists in one insurance network. Cannot be used on its own: send it beside location. A search that breaks this rule is refused before the directory is asked. Give a Organization id, Organization/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256pharm, bare or as http://terminology.hl7.org/CodeSystem/ndh-healthcare-service-category|pharm: every pharmacy, of any kind. Starts a pharmacy search, as specialty does. A pharmacy search needs location.address-state with location.address-postalcode or location.address-city, or one pharmacy's organization or organization.identifier; name narrows it.
1 - 256A NUCC pharmacy code, bare or as http://nucc.org/provider-taxonomy|{code}, or several separated by commas to find pharmacies of any of those kinds: for example 3336C0003X (community or retail) or 3336M0002X (mail order). Starts a pharmacy search. A pharmacy may carry only the general code 333600000X or only a specific one, so send 333600000X,3336C0003X to find either, or service-category=pharm for every kind. Only pharmacy codes (333600000X, 3336C0002X, 3336C0003X, 3336C0004X, 3336H0001X, 3336I0012X, 3336L0003X, 3336M0002X, 3336M0003X, 3336N0007X, 3336S0011X) are served. A pharmacy search needs location.address-state with location.address-postalcode or location.address-city, or one pharmacy's organization or organization.identifier; name narrows it.
1 - 256A pharmacy search's state: the two-letter code of the state the pharmacy's store is in. Required, with a ZIP code or a city, unless the search names one pharmacy.
1 - 50Narrows a pharmacy search to stores whose ZIP code starts with this: a ZIP code, or its first two or more digits. Send it with location.address-state.
1 - 10Narrows a pharmacy search to stores in a city whose name starts with this, so Miami also finds Miami Beach. Two or more letters. Send it with location.address-state.
1 - 100Narrows a pharmacy search to pharmacies whose name, or a name they do business as, starts with this. Two or more letters. Cannot be used on its own, or with a state alone.
1 - 100One pharmacy: the organization that provides it, as a pharmacy search returned it (Organization-{NPI}). Stands alone on a pharmacy search. Give a Organization id, Organization/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256One pharmacy by its NPI, as {system}|{npi} or a bare 10-digit value, under the same systems Organization accepts. Stands alone on a pharmacy search.
1 - 256true or false. Narrows a search; cannot be used on its own.
true, false On a pharmacy search, HealthcareService:organization brings the organization that provides each pharmacy (its NPI, names and phone), and HealthcareService:location its store (address and phone). Repeat the parameter to include several. Included entries do not count toward _count.
1 - 16 elementsHealthcareService:organization, HealthcareService:location A HealthcareService id. Searching by id rather than reading it lets one request also bring the records an _include or _revinclude names.
^[A-Za-z0-9\-.]{1,64}$count only: answers how many records match, as total, with no entries. Cannot be combined with _include, _revinclude, _count or page.
count Results are paged. _count sets the page size (1 to 100); a larger value is refused rather than quietly reduced. Follow link with relation next to continue. The cursor it carries is opaque and must not be constructed or modified.
1 <= x <= 100Continuation cursor. Opaque: follow the next link from a previous response, and never construct or modify it. Cursors expire.
1 - 8192