Clinician Use Cases
Retrieve a Practitioner by Resource Id
In the CDR, clinicians and other healthcare professionals are represented using the Practitioner resource. A Practitioner represents a person who is directly or indirectly involved in the provision of healthcare.
Each Practitioner resource has a unique logical identifier (id) assigned by the CDR. If the resource id is known, the Practioner can be retrieved directly using a FHIR read interaction.
API Request Format
Example API Request
Notes
This retrieves a single Practitioner resource with the specified resource id.
- The resource id is the logical FHIR identifier (
Practitioner.id) assigned by the CDR and is distinct from business identifiers the clinican's professional registration identifier. - If the specified resource does not exist, the server returns an HTTP
404 Not Foundresponse.
If you do not know the resource id, use a FHIR search (for example by identifier, name, or other supported search parameters) to locate the Practitioner resource first, as shown in the sections below.
Supported Search Parameters
The CDR supports the standard search parameters defined in the FHIR R4 specification for the Practitioner resource.
This includes commonly used parameters such as:
identifiernamegivenfamily_revinclude
Please see the refer to the FHIR specification for further details on searching for resources.
The following sections provide examples of common Practitioner searches and demonstrate how search criteria can be combined to refine the results.
Search by Professional Identifier
You can search for a Practitioner using the standard FHIR identifier search parameter. This searches against Practitioner.identifier. In the CDR, this would typically be a professional registration number, such as a GMC, GPhC, NMC, HCPC, GDC or GHPC registration number.
API Request Format
Example API Requests
Search for a doctor using a GMC number:
Search for a nurse using an NMC number:
Search for a pharmacist using a GPhC number:
The following identifier systems are supported:
https://fhir.hl7.org.uk/Id/gdc-numberhttps://fhir.hl7.org.uk/Id/gmc-numberhttps://fhir.hl7.org.uk/Id/gmp-numberhttps://fhir.hl7.org.uk/Id/hcpc-numberhttps://fhir.hl7.org.uk/Id/nmc-numberhttps://fhir.hl7.org.uk/Id/gphc-number
Notes
- Include both the identifier system and registration number when searching.
- Registration numbers uniquely identify healthcare professionals within their respective professional registers.
- The search returns a Bundle containing all matching Practitioner resources.
Search By Name
You can search for a Practitioner using the standard FHIR name search parameter. This searches against Practitioner.name.
The search can use all or part of a practitioner's name.
API Request Format
Example API Requests
Search using the practitioner's family name:
Search using separate given and family name parameters:
Search using a partial name:
Additional parameters can be combined to refine the search. For example:
Notes
- The
namesearch parameter searches across all parts of the practitioner's name. - Searches are not exact and may return multiple matching Practitioners.
- Partial names can be used when the full name is not known.
- Additional search parameters can be combined to further refine the results.
- The search returns a Bundle containing all matching Practitioner resources.
Include Practioner Role in Search Results
In the CDR, the PractitionerRole resource provides information about the role a practitioner performs, such as doctor, nurse or pharmacist. For doctors, it can also include their clinical specialty. A practitioner may have more than one PractitionerRole, for example where they work for different organizations or perform different roles.
The _revinclude parameter can be used to return the PractitionerRole resources that reference each matching Practitioner.
API Request Format
Example API Requests
Search by Professional Registration Number
The following search returns the matching Practitioner together with any PractitionerRole resources that reference them:
Search by Name
The response is a search Bundle containing:
- the Practitioner resources that match the search criteria; and
- any related PractitionerRole resources returned by
_revinclude.
Notes
_revincludefollows references in the reverse direction. In this example, it finds PractitionerRole resources whosePractitionerRole.practitionerreference points to a matching Practitioner.- A Practitioner may have no PractitionerRole or may have several PractitionerRole resources.
- The role is represented in
PractitionerRole.code. - A professional's specialty is represented in
PractitionerRole.specialty. - PractitionerRole may also identify the organization at which the practitioner performs the role.
Submit a Clinician Record to the CDR
A clinician record can be submitted to the CDR by sending a FHIR message Bundle to the $process-message endpoint.
The CDR-ClinicianSubmit MessageDefinition defines the message used to submit details of a clinician, the role they perform and the organisation in which that role is performed. Each message represents one Practitioner, PractitionerRole and Organization combination. Where a clinician has more than one role, or works for more than one organisation, a separate message must be submitted for each combination.
Message Model
The message Bundle must contain:
- a
MessageHeaderresource identifying theclinican-submitevent and referencing the Practioner, PractionerRole and Organization as its focuses; - exactly one
Practitionerresource conforming to the CDR-Practitioner profile; - exactly one
PractitionerRoleresource conforming to the CDR-PractitionerRole profile; and - exactly one
Organizationresource conforming to the CDR-Organization.
Each of these resources is mandatory and must occur exactly once in the message.
The PractitionerRole must reference both the Practitioner and Organization included in the message.
Message Definition
- Overview
- Table
- XML
- JSON
| MessageDefinition |
| id : CDR-ClinicianSubmit |
| url : https://fhir.nhs.wales/MessageDefinition/CDR-ClinicianSubmit |
| name : CDRClinicianSubmit |
| title : Message Definition - CDR - Clinician Submit |
| status : draft |
| experimental : True |
| date : 2026-06-12 |
| publisher : NHS Wales |
| contact |
| name : Data Standards |
| telecom |
| system : email |
| value : data.standards.wales.uk |
| use : work |
| description : Defines the FHIR message used to submit a clinician record to the CDR. Each message must include exactly one Practitioner, one PractitionerRole, and one Organization resource, providing the details of the clinician, the role they perform, and the organization in which that role is performed. Where a clinician performs more than one role, or performs a role for more than one organization, a separate message must be submitted for each practitioner, role, and organization combination. |
| event |
| system : https://fhir.nhs.wales/CodeSystem/CDR-MessageEvents |
| code : clinician-submit |
| focus |
| code : Patient |
| profile : https://fhir.nhs.wales/StructureDefinition/CDR-Practitioner |
| min : 1 |
| max : 1 |
| focus |
| code : PractitionerRole |
| profile : https://fhir.nhs.wales/StructureDefinition/CDR-PractitionerRole |
| min : 1 |
| max : 1 |
| focus |
| code : Organization |
| profile : https://fhir.nhs.wales/StructureDefinition/CDR-Organization |
| min : 1 |
| max : 1 |
| MessageDefinition.id[0] | CDR-ClinicianSubmit |
| MessageDefinition.url[0] | https://fhir.nhs.wales/MessageDefinition/CDR-ClinicianSubmit |
| MessageDefinition.name[0] | CDRClinicianSubmit |
| MessageDefinition.title[0] | Message Definition - CDR - Clinician Submit |
| MessageDefinition.status[0] | draft |
| MessageDefinition.experimental[0] | True |
| MessageDefinition.date[0] | 2026-06-12 |
| MessageDefinition.publisher[0] | NHS Wales |
| MessageDefinition.contact[0].name[0] | Data Standards |
| MessageDefinition.contact[0].telecom[0].system[0] | |
| MessageDefinition.contact[0].telecom[0].value[0] | data.standards.wales.uk |
| MessageDefinition.contact[0].telecom[0].use[0] | work |
| MessageDefinition.description[0] | Defines the FHIR message used to submit a clinician record to the CDR. Each message must include exactly one Practitioner, one PractitionerRole, and one Organization resource, providing the details of the clinician, the role they perform, and the organization in which that role is performed. Where a clinician performs more than one role, or performs a role for more than one organization, a separate message must be submitted for each practitioner, role, and organization combination. |
| MessageDefinition.event[0].system[0] | https://fhir.nhs.wales/CodeSystem/CDR-MessageEvents |
| MessageDefinition.event[0].code[0] | clinician-submit |
| MessageDefinition.focus[0].code[0] | Patient |
| MessageDefinition.focus[0].profile[0] | https://fhir.nhs.wales/StructureDefinition/CDR-Practitioner |
| MessageDefinition.focus[0].min[0] | 1 |
| MessageDefinition.focus[0].max[0] | 1 |
| MessageDefinition.focus[1].code[0] | PractitionerRole |
| MessageDefinition.focus[1].profile[0] | https://fhir.nhs.wales/StructureDefinition/CDR-PractitionerRole |
| MessageDefinition.focus[1].min[0] | 1 |
| MessageDefinition.focus[1].max[0] | 1 |
| MessageDefinition.focus[2].code[0] | Organization |
| MessageDefinition.focus[2].profile[0] | https://fhir.nhs.wales/StructureDefinition/CDR-Organization |
| MessageDefinition.focus[2].min[0] | 1 |
| MessageDefinition.focus[2].max[0] | 1 |
Message Processing Rules
The message supports upsert processing for the Practitioner and conditional creation of the PractitionerRole.
The CDR uses the business identifier provided in Practitioner.identifier to determine whether the Practitioner already exists:
- If no matching Practitioner record exists, a new Practitioner record is created.
- If a Practitioner record already exists with the same business identifier, the existing Practitioner record is used.
The CDR then checks whether a PractitionerRole already exists for the same Practitioner, based on the role recorded in PractitionerRole.code and the organisation referenced in PractitionerRole.organization:
- If no matching PractitionerRole exists, a new PractitionerRole record is created.
- If a matching PractitionerRole already exists, a duplicate PractitionerRole record is not created.
Example FHIR Resources
- Example Bundle – Clinician Submit (Hospital Pharmacist)
- Example Organization (7A5)
- Example Practitioner (Carys Davies)
- Example PractitionerRole (Hospital Pharmacist)
Example API Request
The following example shows the HTTP POST request used to submit a clinican record to the CDR.