cURL
curl "https://api.haau3.com/v1/fhir/r4/Practitioner?identifier=1093209884" \
-H "Authorization: Bearer $HAAU3_API_KEY"import { Haau3 } from "@haau3/sdk";
const haau3 = new Haau3(); // reads HAAU3_API_KEY
const bundle = await haau3.searchPractitioner({ identifier: "1093209884" });
console.log(bundle.entry?.length ?? 0);
from haau3 import Haau3
client = Haau3() # reads HAAU3_API_KEY
bundle = client.search_practitioner(identifier="1093209884")
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.SearchPractitioner(ctx, haau3.SearchPractitionerParams{Identifier: new("1093209884")})
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/Practitioner?identifier=1093209884"
}
],
"entry": [
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/Practitioner/Practitioner-1093209884",
"resource": {
"resourceType": "Practitioner",
"id": "Practitioner-1093209884",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T19:24:16.999300087Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Practitioner"
]
},
"extension": [
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-cms-identity-verified",
"valueBoolean": false
},
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-cms_medicare_enrollment",
"valueBoolean": true
},
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-hhs-in-exclusion-list",
"valueBoolean": false
},
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-cms_aligned_with_data_network",
"valueBoolean": true
}
],
"identifier": [
{
"use": "official",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "PRN",
"display": "Provider number"
}
],
"text": "NPI"
},
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1093209884",
"period": {
"start": "2018-06-15T00:00:00Z"
}
}
],
"active": true,
"name": [
{
"use": "official",
"family": "LEREW",
"given": [
"JAISHREE"
]
},
{
"use": "usual",
"family": "PALANISAMY",
"given": [
"JAISHREE",
"CHANDRAN"
],
"period": {
"start": "2023-05-01T00:00:00Z"
}
},
{
"use": "official",
"family": "LEREW",
"given": [
"JAISHREE",
"PALANISAMY"
]
}
],
"telecom": [
{
"system": "phone",
"value": "2483385392",
"use": "work"
},
{
"system": "phone",
"value": "6053287595",
"use": "work"
},
{
"system": "phone",
"value": "6053288200",
"use": "work"
},
{
"system": "phone",
"value": "6053289000",
"use": "work"
},
{
"system": "phone",
"value": "6053289419",
"use": "work"
},
{
"system": "phone",
"value": "6053331000",
"use": "work"
},
{
"system": "phone",
"value": "6059955635",
"use": "work"
}
],
"address": [
{
"use": "work",
"type": "physical",
"line": [
"1305 W 18th St"
],
"city": "Sioux Falls",
"state": "SD",
"postalCode": "57105",
"country": "US"
},
{
"use": "work",
"type": "physical",
"line": [
"1310 W 22nd St"
],
"city": "Sioux Falls",
"state": "SD",
"postalCode": "57105",
"country": "US"
},
{
"use": "work",
"type": "physical",
"line": [
"4405 E 26th St"
],
"city": "Sioux Falls",
"state": "SD",
"postalCode": "57103",
"country": "US"
},
{
"use": "work",
"type": "physical",
"line": [
"525 N Foster St"
],
"city": "Mitchell",
"state": "SD",
"postalCode": "57301",
"country": "US"
}
],
"gender": "female",
"qualification": [
{
"code": {
"coding": [
{
"system": "http://nucc.org/provider-taxonomy",
"code": "207Y00000X",
"display": "Otolaryngology Physician"
}
],
"text": "Otolaryngology Physician"
}
},
{
"identifier": [
{
"use": "official",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MD",
"display": "Medical license number"
}
]
},
"value": "5101024069"
}
],
"code": {
"coding": [
{
"system": "http://nucc.org/provider-taxonomy",
"code": "207Y00000X",
"display": "Otolaryngology Physician"
}
]
},
"issuer": {
"reference": "Organization/Organization-State-MI"
}
},
{
"identifier": [
{
"use": "official",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MD",
"display": "Medical license number"
}
]
},
"value": "15452"
}
],
"code": {
"coding": [
{
"system": "http://nucc.org/provider-taxonomy",
"code": "207Y00000X",
"display": "Otolaryngology Physician"
}
]
},
"issuer": {
"reference": "Organization/Organization-State-SD"
}
},
{
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/ndh/CodeSystem/FaCeT-credentialCS",
"code": "DO",
"display": "Doctor of Osteopathy"
}
]
}
},
{
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/ndh/CodeSystem/FaCeT-credentialCS",
"code": "MD",
"display": "Doctor of Medicine"
}
]
}
}
]
},
"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": "error",
"code": "forbidden",
"details": {
"coding": [
{
"system": "https://haau3.com/fhir/CodeSystem/api-error",
"code": "test-key-outside-sandbox",
"display": "Test key outside the Sandbox"
}
],
"text": "This is a test key, which works only in the Sandbox (https://api.haau3.com/v1/sandbox/fhir/r4). Send this request with a live key; create one in the dashboard. See https://docs.haau3.com/authentication#test-and-live-keys"
}
}
]
}{
"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>"
]
}
]
}Provider directory
Find a practitioner by NPI or name
Search Practitioner by identifier to resolve an NPI you already hold, or by name to find someone. A search needs one or the other (or an _id): address-city, address-state and active narrow a search but cannot stand alone. Specialties are searched on PractitionerRole.
Three identifier systems are accepted, http://terminology.hl7.org/NamingSystem/npi, http://hl7.org/fhir/sid/us-npi and urn:oid:2.16.840.1.113883.4.6, as well as a bare 10-digit value. All of them resolve the same provider. Responses carry the directory’s own system, http://hl7.org/fhir/sid/us-npi, which may differ from the one you sent. Any other identifier system is refused by name: a system the directory does not index would answer with an empty result, which reads as ‘no such provider’.
One NPI per search. To resolve several, POST a batch Bundle with one entry each.
GET
/
v1
/
fhir
/
r4
/
Practitioner
cURL
curl "https://api.haau3.com/v1/fhir/r4/Practitioner?identifier=1093209884" \
-H "Authorization: Bearer $HAAU3_API_KEY"import { Haau3 } from "@haau3/sdk";
const haau3 = new Haau3(); // reads HAAU3_API_KEY
const bundle = await haau3.searchPractitioner({ identifier: "1093209884" });
console.log(bundle.entry?.length ?? 0);
from haau3 import Haau3
client = Haau3() # reads HAAU3_API_KEY
bundle = client.search_practitioner(identifier="1093209884")
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.SearchPractitioner(ctx, haau3.SearchPractitionerParams{Identifier: new("1093209884")})
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/Practitioner?identifier=1093209884"
}
],
"entry": [
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/Practitioner/Practitioner-1093209884",
"resource": {
"resourceType": "Practitioner",
"id": "Practitioner-1093209884",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T19:24:16.999300087Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Practitioner"
]
},
"extension": [
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-cms-identity-verified",
"valueBoolean": false
},
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-cms_medicare_enrollment",
"valueBoolean": true
},
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-hhs-in-exclusion-list",
"valueBoolean": false
},
{
"url": "https://directory.cms.gov/fhir/StructureDefinition/base-ext-cms_aligned_with_data_network",
"valueBoolean": true
}
],
"identifier": [
{
"use": "official",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "PRN",
"display": "Provider number"
}
],
"text": "NPI"
},
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "1093209884",
"period": {
"start": "2018-06-15T00:00:00Z"
}
}
],
"active": true,
"name": [
{
"use": "official",
"family": "LEREW",
"given": [
"JAISHREE"
]
},
{
"use": "usual",
"family": "PALANISAMY",
"given": [
"JAISHREE",
"CHANDRAN"
],
"period": {
"start": "2023-05-01T00:00:00Z"
}
},
{
"use": "official",
"family": "LEREW",
"given": [
"JAISHREE",
"PALANISAMY"
]
}
],
"telecom": [
{
"system": "phone",
"value": "2483385392",
"use": "work"
},
{
"system": "phone",
"value": "6053287595",
"use": "work"
},
{
"system": "phone",
"value": "6053288200",
"use": "work"
},
{
"system": "phone",
"value": "6053289000",
"use": "work"
},
{
"system": "phone",
"value": "6053289419",
"use": "work"
},
{
"system": "phone",
"value": "6053331000",
"use": "work"
},
{
"system": "phone",
"value": "6059955635",
"use": "work"
}
],
"address": [
{
"use": "work",
"type": "physical",
"line": [
"1305 W 18th St"
],
"city": "Sioux Falls",
"state": "SD",
"postalCode": "57105",
"country": "US"
},
{
"use": "work",
"type": "physical",
"line": [
"1310 W 22nd St"
],
"city": "Sioux Falls",
"state": "SD",
"postalCode": "57105",
"country": "US"
},
{
"use": "work",
"type": "physical",
"line": [
"4405 E 26th St"
],
"city": "Sioux Falls",
"state": "SD",
"postalCode": "57103",
"country": "US"
},
{
"use": "work",
"type": "physical",
"line": [
"525 N Foster St"
],
"city": "Mitchell",
"state": "SD",
"postalCode": "57301",
"country": "US"
}
],
"gender": "female",
"qualification": [
{
"code": {
"coding": [
{
"system": "http://nucc.org/provider-taxonomy",
"code": "207Y00000X",
"display": "Otolaryngology Physician"
}
],
"text": "Otolaryngology Physician"
}
},
{
"identifier": [
{
"use": "official",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MD",
"display": "Medical license number"
}
]
},
"value": "5101024069"
}
],
"code": {
"coding": [
{
"system": "http://nucc.org/provider-taxonomy",
"code": "207Y00000X",
"display": "Otolaryngology Physician"
}
]
},
"issuer": {
"reference": "Organization/Organization-State-MI"
}
},
{
"identifier": [
{
"use": "official",
"type": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MD",
"display": "Medical license number"
}
]
},
"value": "15452"
}
],
"code": {
"coding": [
{
"system": "http://nucc.org/provider-taxonomy",
"code": "207Y00000X",
"display": "Otolaryngology Physician"
}
]
},
"issuer": {
"reference": "Organization/Organization-State-SD"
}
},
{
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/ndh/CodeSystem/FaCeT-credentialCS",
"code": "DO",
"display": "Doctor of Osteopathy"
}
]
}
},
{
"code": {
"coding": [
{
"system": "http://hl7.org/fhir/us/ndh/CodeSystem/FaCeT-credentialCS",
"code": "MD",
"display": "Doctor of Medicine"
}
]
}
}
]
},
"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": "error",
"code": "forbidden",
"details": {
"coding": [
{
"system": "https://haau3.com/fhir/CodeSystem/api-error",
"code": "test-key-outside-sandbox",
"display": "Test key outside the Sandbox"
}
],
"text": "This is a test key, which works only in the Sandbox (https://api.haau3.com/v1/sandbox/fhir/r4). Send this request with a live key; create one in the dashboard. See https://docs.haau3.com/authentication#test-and-live-keys"
}
}
]
}{
"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
A live platform API key (haau3_sk_live_…), sent as Authorization: Bearer <key>. It works for every service outside the Sandbox. Create one on the API keys page at https://platform.haau3.com.
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
An NPI, as {system}|{npi} or a bare 10-digit value. Accepted systems: http://terminology.hl7.org/NamingSystem/npi, http://hl7.org/fhir/sid/us-npi, urn:oid:2.16.840.1.113883.4.6. All of them resolve the same provider. Responses carry the directory's own system, http://hl7.org/fhir/sid/us-npi, which may differ from the one you sent. One NPI per search; use a batch Bundle to resolve several. Any other identifier system is refused by name rather than searched, because a system the source does not index would answer with an empty result that reads as 'no such provider'.
Required string length:
1 - 256Matches across the whole name.
Required string length:
1 - 100The family name.
Required string length:
1 - 100A given name.
Required string length:
1 - 100Narrows a search by city; cannot be used on its own. Matches any of the practitioner's addresses, so a result can still list addresses in another city.
Required string length:
1 - 100Narrows a search by state; cannot be used on its own. Matches any of the practitioner's addresses, so a result can still list addresses in another state.
Required string length:
1 - 50true or false. Narrows a search; cannot be used on its own.
Available options:
true, false PractitionerRole:practitioner brings the practitioner's roles into the same bundle. Repeat the parameter to include several. Included entries do not count toward _count. The directory returns at most 100 included records per page; a page with more is refused with a 502 rather than served short.
Required array length:
1 - 16 elementsAvailable options:
PractitionerRole:practitioner A Practitioner id. Searching by id rather than reading it lets one request also bring the records an _include or _revinclude names.
Pattern:
^[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.
Available options:
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.
Required range:
1 <= x <= 100Continuation cursor. Opaque: follow the next link from a previous response, and never construct or modify it. Cursors expire.
Required string length:
1 - 8192