curl "https://api.haau3.com/v1/fhir/r4/PractitionerRole?practitioner=Practitioner-1093209884&_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.searchPractitionerRole({
practitioner: "Practitioner-1093209884",
_count: 2,
});
console.log(bundle.entry?.length ?? 0);
from haau3 import Haau3
client = Haau3() # reads HAAU3_API_KEY
bundle = client.search_practitioner_role(practitioner="Practitioner-1093209884", 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.SearchPractitionerRole(ctx, haau3.SearchPractitionerRoleParams{Practitioner: new("Practitioner-1093209884"), 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/PractitionerRole?practitioner=Practitioner-1093209884&_count=2"
},
{
"relation": "next",
"url": "https://api.haau3.com/v1/fhir/r4/PractitionerRole?practitioner=Practitioner-1093209884&_count=2&page=AAMA-EFRSURBSGd2bzlHTkh2NkZNeXNGMkNKelNQaUp6aCtWTXNCNXh6R0owVG0xQ1RtRzZRSHhvWlEzNFJSWHQza0tnaEdWM0haYUFBQUFmakI4QmdrcWhraUc5dzBCQndhZ2J6QnRBZ0VBTUdnR0NTcUdTSWIzRFFFSEFUQWVCZ2xnaGtnQlpRTUVBUzR3RVFRTWFORzVkbjloMHNFMSsrNm5BZ0VRZ0Rzb3kzRTBRczhLbmFocjhwN01lWktWWDZkcXJhNFZLdXI4Z0xHTXN6M1lCRDY0Tk93SjZSMCtqSlc3RDZxSDlBaEhzL0Nwc3JlR3ZGaVBxZz09f_DsjRpKEixXbrlvCvUC7gZLCZZmP--xZPgTrdKMf2PmkUIG_P9qov8JINwWhj7TWPOMyo_Q2djzvPN1pTlAC2FhzC6QPk_co8qGuEKM7s08xE7hT4GPMHM_DRnijBykV4A-Jkezg7xMdJwzw1s9ccQKv5-On-DN-RxdGnJbSOwv1r5YGz-YD7lN-K37bVwGeL7yGdK9-UObPc5emRevcRgzsZ7RX0krSCjv_LoddGitY_QLBN0lpYvy373aeipj7FzudYhmJ-9Ti1xzbVwKr2GI-0OkI3Mupv8mjt-bAt6p42BoxIzs0N3j3IdS5_r-zs6wJRNhs76IrmWy5qeSW4M8zB-_jVyzM0d67gVc7Z93smouP8lX5vDkeFPsoUbiFl57eKo5pFsOQ5Y1WALdFBJBPhNubRAS8oME3VxpMgs2Pi9ZQfuxJHyFe7RG4uEWwe5uJ9AGc1XbWeUJhlrUVbfN4QIVIg0cTi4h48yLKWaRak049q9q3fOmrIZOCqTZNmKXzxw5mNseSGEQ51ys78pBZCmY03gUlLV_hDdSy9xbDzmloslxEK9ZVzf8H0KJnbNArGXPs5lMSotAvCh00dGwfOWaquzN44cuUS5_OO-Wr8HgjDHNPdRkTqL_uVT_-5KBA9P9GZc3wfZQRoXKeP9aky2HGzkpxVblIj0ztGxd-cJvy-JXOSRctP7Q_tFpEuRnmhpkgoj2LDFiNI611wfoOEKfod1M_7FJg6QZFkt-LIqoZ3IxR8JII-S-4OPvTuYrFQM5OUvTIPqutl8E8e4wGzoAO3aPA08IYyN-VGQmodY5F5C8vuzuSx0f0U7u3Ktte35N7nchDtgMuNfn05Xg0Y72XlXCb0gOqg3G0vUaq-7ItbCOExHnUYBzayYaaG-XjfyqAsgo1SGi0D4F6ZIzYgdOysOhqwU4aCVha9cIc8netagd1B-gn7cWMbb7S5LE0UGKjW9P_sch1Z5EECNVsfgOuk-jyMudmK-NRn16ExmcTG8odSvvUPw5s21EkLI3Xz7aacI8amu1CXShiQ%3D%3D"
}
],
"entry": [
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/PractitionerRole/PractitionerRole-179421b5-5919-4f54-84c9-a4473b68f74c",
"resource": {
"resourceType": "PractitionerRole",
"id": "PractitionerRole-179421b5-5919-4f54-84c9-a4473b68f74c",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T20:22:07.148389167Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-PractitionerRole"
]
},
"extension": [
{
"url": "http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-newpatients",
"extension": [
{
"url": "acceptingPatients",
"valueCodeableConcept": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/accepting-patients",
"code": "newpt",
"display": "Accepting new and existing patients"
}
]
}
}
]
}
],
"active": true,
"period": {
"start": "2024-09-09T00:00:00Z"
},
"practitioner": {
"reference": "Practitioner/Practitioner-1093209884"
},
"organization": {
"reference": "Organization/Organization-1417927559"
},
"location": [
{
"reference": "Location/Location-91b06a35-8b0e-4aad-abdf-583fa4f132a9"
}
],
"telecom": [
{
"system": "phone",
"value": "6053289419",
"use": "work"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/PractitionerRole/PractitionerRole-4dc9b35e-c888-4a59-b33e-0658eee88e4c",
"resource": {
"resourceType": "PractitionerRole",
"id": "PractitionerRole-4dc9b35e-c888-4a59-b33e-0658eee88e4c",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T20:18:20.113892082Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-PractitionerRole"
]
},
"extension": [
{
"url": "http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-newpatients",
"extension": [
{
"url": "acceptingPatients",
"valueCodeableConcept": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/accepting-patients",
"code": "newpt",
"display": "Accepting new and existing patients"
}
]
}
}
]
}
],
"active": true,
"period": {
"start": "2024-09-09T00:00:00Z"
},
"practitioner": {
"reference": "Practitioner/Practitioner-1093209884"
},
"organization": {
"reference": "Organization/Organization-1093090342"
},
"location": [
{
"reference": "Location/Location-91b06a35-8b0e-4aad-abdf-583fa4f132a9"
},
{
"reference": "Location/Location-b0f5435e-f842-4790-9103-1b07d3b2caf1"
},
{
"reference": "Location/Location-be799f58-4bbc-4f3a-9af4-e04f9d8b6314"
},
{
"reference": "Location/Location-e009883a-9bf1-40ab-8cd9-c57ba2f7546d"
}
],
"telecom": [
{
"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"
}
]
},
"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>"
]
}
]
}Find practitioner roles
Search PractitionerRole: the organizations, specialties, locations and networks practitioners are associated with. A search names a practitioner, an organization, a location or an endpoint; specialty (NUCC), new-patient and active narrow it.
network and new-patient-from-network follow the directory’s own rule: each needs a practitioner, organization, location or specialty beside it, and a search without one is refused before the directory is asked. A network search beside a practitioner or an organization answers in under a second; beside a specialty or a busy location the directory can take 10 to 15 seconds. The directory’s network data is sparse, so a role a network’s records do not list is not shown to be out of network.
identifier is not offered because the directory does not carry identifiers on these resources.
curl "https://api.haau3.com/v1/fhir/r4/PractitionerRole?practitioner=Practitioner-1093209884&_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.searchPractitionerRole({
practitioner: "Practitioner-1093209884",
_count: 2,
});
console.log(bundle.entry?.length ?? 0);
from haau3 import Haau3
client = Haau3() # reads HAAU3_API_KEY
bundle = client.search_practitioner_role(practitioner="Practitioner-1093209884", 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.SearchPractitionerRole(ctx, haau3.SearchPractitionerRoleParams{Practitioner: new("Practitioner-1093209884"), 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/PractitionerRole?practitioner=Practitioner-1093209884&_count=2"
},
{
"relation": "next",
"url": "https://api.haau3.com/v1/fhir/r4/PractitionerRole?practitioner=Practitioner-1093209884&_count=2&page=AAMA-EFRSURBSGd2bzlHTkh2NkZNeXNGMkNKelNQaUp6aCtWTXNCNXh6R0owVG0xQ1RtRzZRSHhvWlEzNFJSWHQza0tnaEdWM0haYUFBQUFmakI4QmdrcWhraUc5dzBCQndhZ2J6QnRBZ0VBTUdnR0NTcUdTSWIzRFFFSEFUQWVCZ2xnaGtnQlpRTUVBUzR3RVFRTWFORzVkbjloMHNFMSsrNm5BZ0VRZ0Rzb3kzRTBRczhLbmFocjhwN01lWktWWDZkcXJhNFZLdXI4Z0xHTXN6M1lCRDY0Tk93SjZSMCtqSlc3RDZxSDlBaEhzL0Nwc3JlR3ZGaVBxZz09f_DsjRpKEixXbrlvCvUC7gZLCZZmP--xZPgTrdKMf2PmkUIG_P9qov8JINwWhj7TWPOMyo_Q2djzvPN1pTlAC2FhzC6QPk_co8qGuEKM7s08xE7hT4GPMHM_DRnijBykV4A-Jkezg7xMdJwzw1s9ccQKv5-On-DN-RxdGnJbSOwv1r5YGz-YD7lN-K37bVwGeL7yGdK9-UObPc5emRevcRgzsZ7RX0krSCjv_LoddGitY_QLBN0lpYvy373aeipj7FzudYhmJ-9Ti1xzbVwKr2GI-0OkI3Mupv8mjt-bAt6p42BoxIzs0N3j3IdS5_r-zs6wJRNhs76IrmWy5qeSW4M8zB-_jVyzM0d67gVc7Z93smouP8lX5vDkeFPsoUbiFl57eKo5pFsOQ5Y1WALdFBJBPhNubRAS8oME3VxpMgs2Pi9ZQfuxJHyFe7RG4uEWwe5uJ9AGc1XbWeUJhlrUVbfN4QIVIg0cTi4h48yLKWaRak049q9q3fOmrIZOCqTZNmKXzxw5mNseSGEQ51ys78pBZCmY03gUlLV_hDdSy9xbDzmloslxEK9ZVzf8H0KJnbNArGXPs5lMSotAvCh00dGwfOWaquzN44cuUS5_OO-Wr8HgjDHNPdRkTqL_uVT_-5KBA9P9GZc3wfZQRoXKeP9aky2HGzkpxVblIj0ztGxd-cJvy-JXOSRctP7Q_tFpEuRnmhpkgoj2LDFiNI611wfoOEKfod1M_7FJg6QZFkt-LIqoZ3IxR8JII-S-4OPvTuYrFQM5OUvTIPqutl8E8e4wGzoAO3aPA08IYyN-VGQmodY5F5C8vuzuSx0f0U7u3Ktte35N7nchDtgMuNfn05Xg0Y72XlXCb0gOqg3G0vUaq-7ItbCOExHnUYBzayYaaG-XjfyqAsgo1SGi0D4F6ZIzYgdOysOhqwU4aCVha9cIc8netagd1B-gn7cWMbb7S5LE0UGKjW9P_sch1Z5EECNVsfgOuk-jyMudmK-NRn16ExmcTG8odSvvUPw5s21EkLI3Xz7aacI8amu1CXShiQ%3D%3D"
}
],
"entry": [
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/PractitionerRole/PractitionerRole-179421b5-5919-4f54-84c9-a4473b68f74c",
"resource": {
"resourceType": "PractitionerRole",
"id": "PractitionerRole-179421b5-5919-4f54-84c9-a4473b68f74c",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T20:22:07.148389167Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-PractitionerRole"
]
},
"extension": [
{
"url": "http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-newpatients",
"extension": [
{
"url": "acceptingPatients",
"valueCodeableConcept": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/accepting-patients",
"code": "newpt",
"display": "Accepting new and existing patients"
}
]
}
}
]
}
],
"active": true,
"period": {
"start": "2024-09-09T00:00:00Z"
},
"practitioner": {
"reference": "Practitioner/Practitioner-1093209884"
},
"organization": {
"reference": "Organization/Organization-1417927559"
},
"location": [
{
"reference": "Location/Location-91b06a35-8b0e-4aad-abdf-583fa4f132a9"
}
],
"telecom": [
{
"system": "phone",
"value": "6053289419",
"use": "work"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://api.haau3.com/v1/fhir/r4/PractitionerRole/PractitionerRole-4dc9b35e-c888-4a59-b33e-0658eee88e4c",
"resource": {
"resourceType": "PractitionerRole",
"id": "PractitionerRole-4dc9b35e-c888-4a59-b33e-0658eee88e4c",
"meta": {
"versionId": "1",
"lastUpdated": "2026-10-14T20:18:20.113892082Z",
"profile": [
"http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-PractitionerRole"
]
},
"extension": [
{
"url": "http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-newpatients",
"extension": [
{
"url": "acceptingPatients",
"valueCodeableConcept": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/accepting-patients",
"code": "newpt",
"display": "Accepting new and existing patients"
}
]
}
}
]
}
],
"active": true,
"period": {
"start": "2024-09-09T00:00:00Z"
},
"practitioner": {
"reference": "Practitioner/Practitioner-1093209884"
},
"organization": {
"reference": "Organization/Organization-1093090342"
},
"location": [
{
"reference": "Location/Location-91b06a35-8b0e-4aad-abdf-583fa4f132a9"
},
{
"reference": "Location/Location-b0f5435e-f842-4790-9103-1b07d3b2caf1"
},
{
"reference": "Location/Location-be799f58-4bbc-4f3a-9af4-e04f9d8b6314"
},
{
"reference": "Location/Location-e009883a-9bf1-40ab-8cd9-c57ba2f7546d"
}
],
"telecom": [
{
"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"
}
]
},
"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>"
]
}
]
}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 roles one practitioner holds. Give a Practitioner id, Practitioner/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256The roles held at one organization. Give a Organization id, Organization/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256The roles held at one location. Give a Location id, Location/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256The roles reached through one endpoint. Give a Endpoint id, Endpoint/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256A NUCC Health Care Provider Taxonomy code, bare or as http://nucc.org/provider-taxonomy|{code} (for example 207RC0000X, cardiovascular disease). Any other system is refused, because the directory codes specialties in NUCC alone and would answer another system with nothing. Narrows a search; cannot be used on its own.
1 - 256The roles the directory lists in one insurance network (an Organization of type ntwk). Cannot be used on its own: send it beside practitioner, organization, location or specialty. A search that breaks this rule is refused before the directory is asked. Beside a specialty or a busy location the directory can take 10 to 15 seconds. A role the network's records do not list is not shown to be out of network: the directory's network data is sparse. Give a Organization id, Organization/{id}, or the fullUrl this service returned. An address on another server is refused.
1 - 256The roles accepting new patients from one insurance network. Cannot be used on its own: send it beside practitioner, organization, location or specialty. 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 - 256Whether the role accepts new patients: newpt, nopt, existptonly or existptfam, bare or under http://terminology.hl7.org/CodeSystem/accepting-patients. Narrows a search; cannot be used on its own.
1 - 256true or false. Narrows a search; cannot be used on its own.
true, false Bring the records a role points to into the same bundle: PractitionerRole:practitioner, PractitionerRole:organization, PractitionerRole:location, PractitionerRole:network or PractitionerRole:endpoint. Repeat the parameter to include several. Included entries do not count toward _count.
1 - 16 elementsPractitionerRole:practitioner, PractitionerRole:organization, PractitionerRole:location, PractitionerRole:network, PractitionerRole:endpoint A PractitionerRole 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