A specific set of Roles/Locations/specialties/services that a practitioner may perform at an organisation for a period of time.

0. References

1. Read

Return a single PractitionerRole for the specified id.

All requests SHALL contain a valid ‘Authorization’ header and SHALL contain an ‘Accept’ header. The `Accept` header indicates the format of the response the client is able to understand, this will be one of the following application/json+fhir or application/xml+fhir.

1.1. Response

A full set of response codes can be found here API Response Codes. FHIR Servers SHALL support the following response codes:

200 successful operation
404 resource not found
410 resource deleted

Fetches a bundle of all PractitionerRole resources for the specified search criteria.

All requests SHALL contain a valid ‘Authorization’ header and SHALL contain an ‘Accept’ header. The `Accept` header indicates the format of the response the client is able to understand, this will be one of the following application/json+fhir or application/xml+fhir.

2.1. Search Parameters

This implementation guide outlines some suggested search parameters for the Practitioner Role resource in the table below. To be conformant, provider systems are required to implement all of the SHALL parameters. Provider systems may implement the full list of search parameters for the Practitioner Role resource (HL7 FHIR STU3 Practitioner Role).


Name Type Description Conformance Path
identifier token A practitioner's Identifier SHOULD PractitionerRole.identifier
organization reference The identity of the organisation the practitioner represents / acts on behalf of SHALL PractitionerRole.organization (Organization)
practitioner reference Practitioner that is able to provide the defined services for the organisation SHALL PractitionerRole.practitioner (Practitioner)

2.1.1. identifier (SDS Id or ODS Code)

See token for details on this parameter.

GET [baseUrl]/PractitionerRole?identifier=https://fhir.nhs.uk/Id/sds-user-id|123456

Return all PractitionerRole resources with SDS User ID of 123456.

2.1.2. organization

See reference for details on this parameter.

GET [baseUrl]/PractitionerRole?organization=1

Return all PractitionerRole resources that have a organization with Organization Id of 1.

2.1.3. practitioner

See reference for details on this parameter.

GET [baseUrl]/PractitionerRole?practitioner=1

Return all PractitionerRole resources that have a practitioner with Practitioner Id of 1.

2.2. Search Response

If the search fails (cannot be executed, not that there is no matches), the return value is a status code 4xx or 5xx with an OperationOutcome.

If the search succeeds, the return content is a Bundle with type = searchset containing the results of the search as a list of resources in a defined order. The result list can be long, so servers MAY use paging. If they do, they SHALL use this Paging method for breaking the list into pages if appropriate. The server MAY also return an OperationOutcome resource with additional information about the search; if one is sent it SHALL NOT include any errors, and it shall be marked with an entry mode of include.

A full set of response codes can be found here API Response Codes. FHIR Servers SHALL support the following response codes:

200 successful operation
404 resource not found
410 resource deleted

3. Example

3.1 cURL

Return all PractitionerRole resources for Practitioner with an id of 1, the format of the response body will be xml. Replace ‘baseUrl’ with the actual base Url of the FHIR Server.

curl -X GET -H 'Accept: application/xml+fhir' -H 'Authorisation: BEARER [token]' -v 'https://data.developer.nhs.uk/ccri/STU3/PractitionerRole?practitioner=1'

3.2 Explore the Response

Explore the response in XML & JSON on the Reference Implementation below

Reference Implementation

XML Practitioner id search RI viewer
JSON Practitioner id search RI viewer
Tags: rest fhir identification api