> ## Documentation Index > Fetch the complete documentation index at: https://docs.haau3.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/fhir/r4/PractitionerRole openapi: 3.1.0 info: title: haau3 Platform API version: 1.0.0-preview.4 description: >- The haau3 platform API is in preview: it may change as we build, usually to add features or improve performance. Endpoints require an API key, sent as `Authorization: Bearer `. Requests without a valid key return 401. Create a key in the dashboard at https://platform.haau3.com; a new organization starts on the free Developer plan. From 2026-11-01 a request past one of its plan's limits (requests a minute on every plan, requests a month on Developer) returns 429 with `Retry-After`. Every error under `/v1/fhir` is a FHIR `OperationOutcome` and every other error an RFC 9457 problem; https://docs.haau3.com/errors lists every status, whether to retry it, and what a method a path does not take answers. servers: - url: https://api.haau3.com description: Production security: - bearerAuth: [] tags: - name: Scheduling description: 'Provider availability (SMART Scheduling Links): slots and publishers.' - name: FHIR base description: >- What the FHIR R4 base at `/v1/fhir/r4` answers for every service on it: the `CapabilityStatement` that lists them all, and batch Bundles that carry several requests to any of them in one round trip. - name: Terminology description: >- FHIR terminology operations over the code systems listed in TerminologyCapabilities. Some are resolved from their own source when you ask; others are held here at a named release, which that resource also names. - name: Provider directory description: >- CMS's National Provider Directory as FHIR R4: practitioners and their roles, organizations, payers and insurance networks, network membership, healthcare services, locations and endpoints. Every parameter the service serves is declared here, and any other is refused by name rather than ignored. - name: Questionnaires description: >- FHIR Questionnaire, served as its source publishes it. This service holds copies of a curated set and reaches any other questionnaire its source publishes by canonical URL, as well as forms published at their own address under places this service is set up to reach. Read one by id, and build the QuestionnaireResponse in your own application. - name: Plan Benefits description: >- FHIR InsurancePlan: what a Medicare Advantage or ACA Marketplace plan covers and what a member pays, read from the files CMS publishes. Every plan names the CMS release it was read from. Read a plan by its id, or search by identifier, name, state or county, and check whether the CMS National Provider Directory lists providers in a plan's network. - name: MedList description: >- One reconciled medication list from one patient's FHIR medication records, as US Core MedicationRequests with a Provenance for each. This operation receives patient data, so send it only under an executed agreement. paths: /v1/fhir/r4/PractitionerRole: get: tags: - Provider directory summary: Find practitioner roles description: >- 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. operationId: searchPractitionerRole parameters: - name: practitioner in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- The roles one practitioner holds. Give a Practitioner id, `Practitioner/{id}`, or the `fullUrl` this service returned. An address on another server is refused. example: Practitioner-1093209884 - name: organization in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- The roles held at one organization. Give a Organization id, `Organization/{id}`, or the `fullUrl` this service returned. An address on another server is refused. - name: location in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- The roles held at one location. Give a Location id, `Location/{id}`, or the `fullUrl` this service returned. An address on another server is refused. - name: endpoint in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- The roles reached through one endpoint. Give a Endpoint id, `Endpoint/{id}`, or the `fullUrl` this service returned. An address on another server is refused. - name: specialty in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- A 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. - name: network in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- The 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. - name: new-patient-from-network in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- The 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. - name: new-patient in: query required: false schema: type: string minLength: 1 maxLength: 256 description: >- Whether 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. - name: active in: query required: false schema: type: string enum: - 'true' - 'false' description: '`true` or `false`. Narrows a search; cannot be used on its own.' - name: _include in: query required: false schema: minItems: 1 maxItems: 16 type: array items: type: string enum: - PractitionerRole:practitioner - PractitionerRole:organization - PractitionerRole:location - PractitionerRole:network - PractitionerRole:endpoint style: form explode: true description: >- 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`. - name: _id in: query required: false schema: type: string pattern: ^[A-Za-z0-9\-.]{1,64}$ description: >- A PractitionerRole id. Searching by id rather than reading it lets one request also bring the records an `_include` or `_revinclude` names. - name: _summary in: query required: false schema: type: string enum: - count description: >- `count` only: answers how many records match, as `total`, with no entries. Cannot be combined with `_include`, `_revinclude`, `_count` or `page`. - name: _count in: query required: false schema: type: integer minimum: 1 maximum: 100 description: >- 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. example: 2 - name: page in: query required: false schema: type: string minLength: 1 maxLength: 8192 description: >- Continuation cursor. Opaque: follow the `next` link from a previous response, and never construct or modify it. Cursors expire. - $ref: '#/components/parameters/XRequestId' responses: '200': description: >- A FHIR `Bundle` with `type: searchset`. `total` is present when the directory sends one. content: application/fhir+json: schema: $ref: '#/components/schemas/Bundle' examples: A practitioner's roles: summary: A practitioner's roles value: 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 headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '400': description: >- The request named a parameter, identifier system or value this service does not serve. Every unsupported parameter is refused by name, and none is silently ignored, so a search that returns results applied every filter you sent. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '401': $ref: '#/components/responses/FhirUnauthorized' '404': description: No such resource, or no such interaction on this base. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '406': $ref: '#/components/responses/FhirNotAcceptable' '429': $ref: '#/components/responses/FhirTooManyRequests' '500': $ref: '#/components/responses/FhirServerError' '502': description: >- The directory could not be reached, answered in a shape that cannot be served, or answered with more than is served at once: a `_revinclude` past the directory's 100 records on a page, or an answer over 8 MiB. No answer is given: this is never reported as an empty result, which would read as 'no such provider'. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '503': description: >- The directory is rate limiting requests. Send the request again after `Retry-After`. It is also the answer when the API key could not be checked just now, with `Retry-After`. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: Retry-After: description: >- Sent when waiting will help: the API key could not be checked just now, or the source behind this service is rate limiting requests. How many seconds to wait before sending the request again. schema: type: integer minimum: 0 X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' '504': description: The directory did not respond in time. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' x-codeSamples: - lang: bash label: cURL source: > curl "https://api.haau3.com/v1/fhir/r4/PractitionerRole?practitioner=Practitioner-1093209884&_count=2" \ -H "Authorization: Bearer $HAAU3_API_KEY" - lang: typescript label: TypeScript source: | 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); - lang: python label: Python source: > 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", []))) - lang: go label: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/haau3/haau3-go\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := haau3.NewClient() // reads HAAU3_API_KEY\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tbundle, err := client.SearchPractitionerRole(ctx, haau3.SearchPractitionerRoleParams{Practitioner: new(\"Practitioner-1093209884\"), Count: new(2)})\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tfmt.Println(len(bundle.Entry))\n}\n" components: parameters: XRequestId: name: X-Request-Id in: header required: false schema: type: string format: uuid description: >- 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. schemas: Bundle: type: object description: A FHIR R4 [Bundle](https://hl7.org/fhir/R4/bundle.html). properties: resourceType: type: string const: Bundle type: type: string entry: type: array items: type: object additionalProperties: true required: - resourceType additionalProperties: true OperationOutcome: type: object description: >- A FHIR R4 [OperationOutcome](https://hl7.org/fhir/R4/operationoutcome.html). properties: resourceType: type: string const: OperationOutcome issue: type: array items: type: object properties: severity: type: string enum: - fatal - error - warning - information code: type: string details: type: object properties: text: type: string additionalProperties: true diagnostics: type: string expression: type: array items: type: string required: - severity - code additionalProperties: true required: - resourceType - issue headers: XRequestId: description: >- The id haau3 gave this request, a UUID, on every response. Quote it in a question about the response. A problem carries the same id as its `instance`. schema: type: string format: uuid XCorrelationId: description: The `X-Request-Id` you sent, when it was a UUID. schema: type: string format: uuid responses: FhirUnauthorized: description: Missing or invalid API key. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: WWW-Authenticate: description: >- The scheme to authenticate with: `Bearer realm="api.haau3.com"`, with `error="invalid_token"` when a key was sent and not recognised. schema: type: string X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' FhirNotAcceptable: description: >- The request asked for a format other than JSON (`Accept` or `_format`), or for a FHIR release this endpoint does not serve (the `fhirVersion` media-type parameter). content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' FhirTooManyRequests: description: >- A limit of the organization's plan was reached: its requests a minute, or the Developer plan's requests a month. Send the request again after `Retry-After`, which for the monthly limit runs to the 1st of the next month (UTC). content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: Retry-After: description: How many seconds to wait before sending the request again. schema: type: integer minimum: 0 X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' FhirServerError: description: The server failed to process this request. content: application/fhir+json: schema: $ref: '#/components/schemas/OperationOutcome' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-Correlation-Id: $ref: '#/components/headers/XCorrelationId' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your platform API key (`haau3_sk_…`), sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.