---
title: 'PractitionerRole (FHIR R4)'
description: 'FHIR R4 PractitionerRole resource.'
nav: 'API / R4 / PractitionerRole'
order: 160
version: v1
fhir: r4
source: generated
updated: '2026-09-23'
---

# PractitionerRole (FHIR R4)

<FhirResourceHeader fhir="r4" slug="practitionerrole" />

FHIR R4 PractitionerRole resource.

> This reference is generated from the canonical Huli Public API OpenAPI specification and the server's FHIR R4 CapabilityStatement — do not edit it directly.

## FHIR R4 Specification

Official spec: [PractitionerRole — HL7 FHIR R4](https://hl7.org/fhir/R4/practitionerrole.html)

## Supported Interactions

- **read** — Read a single resource by ID (`GET /fhir/R4/{Resource}/{id}`)
- **search-type** — Search resources with query parameters (`GET /fhir/R4/{Resource}?...`)

<Callout variant="note">
Authorized by the SMART scope `system/Practitioner.rs`. This resource inherits an existing scope — no per-resource `system/PractitionerRole.*` scope is minted; requesting one is rejected.
</Callout>

## Scopes

Scopes are shared across FHIR releases — the same `system/PractitionerRole.*` scope grants PractitionerRole access on both `/fhir/R4` and `/fhir/R5`.

- <Scope name="system/Practitioner.rs" /> — see [scope reference](/v1/scopes#system-practitioner-rs)

## Search Parameters

| Parameter | Type | Notes |
|-----------|------|-------|
| `_id` | token | Exact match. For identifiers use `system|value` format. |
| `practitioner` | reference | Resource reference — supply the UUID of the referenced resource. |
| `location` | reference | Resource reference — supply the UUID of the referenced resource. |
| `_count` | number | Integer. For `_count`: default 20, max 100. |
| `_offset` | number | Integer. For `_count`: default 20, max 100. |

## Endpoints

### Read PractitionerRole

Retrieve a single PractitionerRole resource by its ID. This is a read-only
discovery resource, gated by `system/Practitioner.rs`.

<Endpoint method="GET" path="/fhir/R4/PractitionerRole/{id}" />

**Required scope:** <Scope name="system/Practitioner.rs" />

#### Response — 200

```json
{
  "resourceType": "PractitionerRole",
  "id": "ff0e8400-e29b-41d4-a716-446655440090",
  "active": true,
  "practitioner": {
    "reference": "Practitioner/880e8400-e29b-41d4-a716-446655440020"
  },
  "location": [
    {
      "reference": "Location/dd0e8400-e29b-41d4-a716-446655440070"
    }
  ]
}
```

#### Code Samples

:::CodeGroup

```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/Practitioner.rs" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/R4/PractitionerRole/${RESOURCE_ID} \
  -H "Authorization: Bearer ${TOKEN}"
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/PractitionerRole/${id}`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
    },

  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```

```python {label="Python"}
import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}

resp = requests.get(
    f"https://api.huli.ai/fhir/R4/PractitionerRole/{resource_id}",
    headers=headers,
)
resp.raise_for_status()
print(resp.json())
```

```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class getPractitionerRoleExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");
        String resourceId = "RESOURCE_ID";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/PractitionerRole/" + resourceId))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}
```

```go {label="Go"}
import (
    "fmt"
    "net/http"
    "os"
)

func getPractitionerRoleExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/PractitionerRole/"+resourceID+"", nil)
    req.Header.Set("Authorization", "Bearer "+token)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}
```

:::

#### Errors

| Code | Status | Description |
|------|--------|-------------|
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00102](/v1/errors#hpb-00102) | 404 | Resource not found |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |

---

### Search PractitionerRole

Search PractitionerRole resources. Results are returned as a FHIR searchset
Bundle. This is a read-only discovery resource, gated by `system/Practitioner.rs`.

<Endpoint method="GET" path="/fhir/R4/PractitionerRole" />

**Required scope:** <Scope name="system/Practitioner.rs" />

#### Query Parameters

<ParamTable :rows='[{&quot;name&quot;:&quot;_id&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;PractitionerRole resource ID (UUID).&quot;},{&quot;name&quot;:&quot;practitioner&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Filter by Practitioner reference (UUID or `Practitioner/&lt;uuid&gt;`).&quot;},{&quot;name&quot;:&quot;location&quot;,&quot;type&quot;:&quot;string&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Filter by Location reference (UUID or `Location/&lt;uuid&gt;`).&quot;},{&quot;name&quot;:&quot;_count&quot;,&quot;type&quot;:&quot;integer&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Number of results per page (default: 20, max: 100).&quot;},{&quot;name&quot;:&quot;_offset&quot;,&quot;type&quot;:&quot;integer&quot;,&quot;required&quot;:false,&quot;description&quot;:&quot;Number of results to skip (offset-based pagination).&quot;}]' />

#### Response — 200

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "PractitionerRole/ff0e8400-e29b-41d4-a716-446655440090",
      "resource": {
        "resourceType": "PractitionerRole",
        "id": "ff0e8400-e29b-41d4-a716-446655440090",
        "active": true,
        "practitioner": {
          "reference": "Practitioner/880e8400-e29b-41d4-a716-446655440020"
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}
```

#### Code Samples

:::CodeGroup

```bash {label="cURL"}
TOKEN=$(curl -s -X POST https://api.huli.ai/auth/token \
  -d "grant_type=client_credentials" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=${CLIENT_ASSERTION}" \
  -d "scope=system/Practitioner.rs" \
  | jq -r .access_token)

curl -X GET https://api.huli.ai/fhir/R4/PractitionerRole \
  -H "Authorization: Bearer ${TOKEN}"
```

```typescript {label="TypeScript"}
const token = process.env.HULI_ACCESS_TOKEN ?? "";

const response = await fetch(
  `https://api.huli.ai/fhir/R4/PractitionerRole`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${token}`,
    },

  }
);

if (!response.ok) throw new Error(`HTTP ${String(response.status)}`);
const data: unknown = await response.json();
```

```python {label="Python"}
import os
import requests

token = os.environ["HULI_ACCESS_TOKEN"]
headers = {"Authorization": f"Bearer {token}"}

resp = requests.get(
    f"https://api.huli.ai/fhir/R4/PractitionerRole",
    headers=headers,
)
resp.raise_for_status()
print(resp.json())
```

```java {label="Java"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class searchPractitionerRoleExample {
    public static void main(String[] args) throws Exception {
        String token = System.getenv("HULI_ACCESS_TOKEN");

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.huli.ai/fhir/R4/PractitionerRole"))
        .header("Authorization", "Bearer " + token)
        .header("Accept", "application/fhir+json")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

        HttpResponse<String> response =
        client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("status: " + response.statusCode());
        System.out.println(response.body());
    }
}
```

```go {label="Go"}
import (
    "fmt"
    "net/http"
    "os"
)

func searchPractitionerRoleExample() {
    token := os.Getenv("HULI_ACCESS_TOKEN")
    req, _ := http.NewRequest("GET", "https://api.huli.ai/fhir/R4/PractitionerRole", nil)
    req.Header.Set("Authorization", "Bearer "+token)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("error:", err)
        return
    }
    defer resp.Body.Close()
    fmt.Println("status:", resp.Status)
}
```

:::

#### Errors

| Code | Status | Description |
|------|--------|-------------|
| [HPB-00106](/v1/errors#hpb-00106) | 401 | Authentication failed |
| [HPB-00104](/v1/errors#hpb-00104) | 403 | Insufficient scope |
| [HPB-00105](/v1/errors#hpb-00105) | 429 | Rate limit exceeded |

---