Organization/Location Use Cases

Reference data for organisations, hospitals, GP practices, sites and locations is imported into the CDR from the Welsh Reference and Terminology Service (WRTS) each day. Within the CDR, this information is represented using FHIR Organization and Location resources and can be retrieved using standard FHIR read and search interactions.

Retrieve an Organization by Resource Id

Each Organization resource has a unique logical identifier (id) assigned by the CDR. If the resource id is known, the Organization can be retrieved directly using a FHIR read interaction.

API Request Format

Example API Request

Notes

This retrieves a single Organization resource with the specified resource id. If you do not know the resource id, use a FHIR search (for example by identifier, name, address, or other supported search parameters) to locate the Organization resource first, which is shown in the sections below.

• The resource id is the logical FHIR identifier (Organization.id) assigned by the CDR and is distinct from a business identifiers such as an ODS Code.
• If the specified resource does not exist, the server returns an HTTP 404 Not Found response.

Supported Search Parameters

The CDR supports the standard FHIR R4 search parameters defined for the Organization and Location resources.

This includes commonly used parameters such as:

• identifier
• name
• type
• active
• partof
• address
• organization (Location)
• status (Location)

The CDR also supports the standard FHIR search modifiers and prefixes - please see the refer to the FHIR specification for further details on searching for resources.

The only standard FHIR search parameter that is not supported for the Location resource is the near search parameter.

The following sections provide examples of common Organization and Location searches and demonstrate how search criteria can be combined to refine the results.

Search for Organization by Identifier (ODS Code)

You can search for an Organization using its ODS code with the standard FHIR identifier search parameter. This searches against Organization.identifier.

Include both the ODS identifier system and the ODS code value.

API Request Format

Example API Requests

The identifier system for an ODS organization code is https://fhir.nhs.uk/Id/ods-organization-code.

Notes

• Use Organization.identifier rather than Organization.id when searching by ODS code.
• An ODS code uniquely identifies an organisation or site within the ODS dataset.
• The search may return a Bundle containing the matching Organization resource.
• If the FHIR resource id is already known, retrieve the resource directly using GET [base]/Organization/[id].

Search for Organization by Name

You can search for an Organization using the standard FHIR name search parameter. This searches against both Organization.name and Organization.alias, allowing you to search using either the organization's official name or one of its alternative names.

API Request Format

Example API Requests

You can also search using part of an organisation name:

The CDR contains both active and inactive Organization records. You can filter the results using the active search parameter:

or

Notes

• The name search parameter searches both the official organization name (Organization.name) and any alternative names (Organization.alias).
• The search is not an exact match and may return multiple Organizations.
• Partial names can be used to find organizations when the full name is not known.
• The active parameter can be used to limit results to active or inactive organizations.
• The search returns a Bundle containing all matching Organization resources.
• If you know the ODS code for the Organization, searching by identifier will typically return a more precise result.

Search for Organizations by Type

You can search for Organizations using the standard FHIR type search parameter. This searches the coded values held in Organization.type.

The Data Standards Wales Organization profile uses four organization type categories:

• Sector
• Domain
• Classification
• Subclassification

Each category uses a separate code system:

• Sector: https://fhir.nhs.wales/CodeSystem/DataStandardsWales-OrganizationSector
• Domain: https://fhir.nhs.wales/CodeSystem/DataStandardsWales-OrganizationDomain
• Classification: https://fhir.nhs.wales/CodeSystem/DataStandardsWales-OrganizationClassification
• Subclassification: https://fhir.nhs.wales/CodeSystem/DataStandardsWales-OrganizationSubclassification

Include both the code system and code when searching by organization type.

API RequestFormat

Example API Requests

Search by Subclassification

In most cases, the subclassification provides the most specific and useful way to search for a particular kind of organization.

For example, the following search returns Organizations with a subclassification of gp-practice:

Search by Type and Parent Organization

The partof.identifier chained search parameter can be used to find Organizations that are part of another Organization identified by its ODS code.

For example, the following search returns active GP practices that are part of the Health Board with ODS code 7A3:

Search Using All Organization Type Categories

The four type categories can be combined to make the search more specific. Each repeated type parameter adds another condition to the search.

For example, the following search returns active, private, primary care Organizations in the health domain, that were of subclassification type GP practice.

Notes

• The type parameter is a token search, using the format [system]|[code].
• Subclassification will normally provide the most precise organization type for common searches.
• Sector, domain, classification and subclassification can be combined where a more specific search is required.
• Additional parameters such as active, identifier, name and partof.identifier can be added to refine the results.
• The search returns a Bundle containing all matching Organization resources.

Retrieve a Location by Resource Id

Each Location resource has a unique logical identifier (id) assigned by the CDR. If the resource id is known, the Location can be retrieved directly using a FHIR read interaction.

API Request Format

Example API Request

Notes

This retrieves a single Location resource with the specified resource id.

• The resource id is the logical FHIR identifier (Location.id) assigned by the CDR and is distinct from other business identifiers such as WRTS Location Code.
• If the specified resource does not exist, the server returns an HTTP 404 Not Found response.

If you do not know the resource id, use a FHIR search (for example by address, organization, or other supported search parameters) to locate the Location resource first, as shown in the sections below.

Search for Locations by Address

You can search for a Location using the standard FHIR address search parameter. This searches the address details held in Location.address.

The search can use all or part of an address, depending on the information available.

API Request Format

Example API Requests

Search using part of the address:

Search using a town or city:

Search using a postcode:

Search using both the first line of the address and postcode:

Notes

• The address search parameter searches across the Location address fields, including address lines, city and postcode.
• Combining address parameters helps narrow the search and reduce the number of matches returned.
• Additional parameters, such as name, identifier, organization and active, can be combined to further refine the results.
• The search returns a Bundle containing all matching Location resources.

Search for Locations Managed by an Organization

You can search for Locations that are managed by a particular Organization using the standard FHIR organization search parameter. This searches the Location.managingOrganization reference.

The organization.identifier chained search parameter can be used to identify the Organization by its ODS code.

API Request Format

Example API Request

The following search returns all GP surgery Locations managed by the Organization with ODS code W97614 (Vale Family Practice):

Additional search parameters can be added to refine the results. For example, to return only active Locations:

Notes

• The organization.identifier chained search parameter identifies the managing Organization using its ODS code.
• The search returns all Locations whose managingOrganization reference points to the specified Organization.
• Additional search parameters, such as name, address, identifier and active, can be combined to further refine the results.
• The search returns a Bundle containing all matching Location resources.