Interactions

The ODS FHIR R4 API allows healthcare professionals to use healthcare applications acting as API consumers to search for, read and display organisation information.

The ODS FHIR R4 API provides 2 endpoints:

- /Organization
- /OrganizationAffiliation

While specific supported search parameters have been included for guidance, additional parameters and general guidance on searching is available here: FHIR Search.

Read an Organisation Record by ID

HTTP request and Headers

GET {fhir-server}/Organization?{id}

Authorization – {Bearer Token}

Parameters

The Organisation Code

  • {id}
  • e.g. 4VE03


ods-interations-get

HTTP Response Body

Outcome Response
Record Found Organization - Example - Organization 4VE03
Invalid ID OperationOutcome -
Command 'pagelink' could not render: Page not found.

Query for an Organisation Record using Search Parameters

HTTP request and Headers

GET {fhir-server}/Organization?

Authorization – {Bearer Token}

Parameters

active – a boolean flag for active only or inactive only organizations

  • active={active}
  • e.g. active=True

type – kind of organization
Can be used to search for organizations with specific ODSRecordClass or ODSRecordUseType values

  • type={type}
  • e.g. type=https://fhir.nhs.uk/England/CodeSystem/England-ODSRecordUseType|Full
  • e.g. type=https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRecordClass|RC1

name – the name associated with the organization

  • name={name}
  • e.g. name=ATOS%20MEDICAL

lastChangeDate – the date when ODS last modified the record
Supports: eq (equal), lt (less than), gt (greater than), and can be compounded to retrieve results between two dates

  • lastChangeDate={lastChangeDate}
  • e.g. lastChangeDate=eq2020-09-04
  • e.g. lastChangeDate=gt2020-09-01

roleCode – searches on all ODS OrganizationRole assignments, via the roleCode element

  • roleCode={roleCode}
  • e.g. roleCode=https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole|RO94

activeRoleCode – searches on active ODS OrganizationRole assignments, via the roleCode element

  • activeRoleCode={activeRoleCode}
  • e.g. roleCode=https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole|RO182


ods-interations-search

HTTP Response Body

Outcome Response
Record Found Bundle - Example - Organization Search Result
No Records Found Bundle - Example - No Organisation Search Results Found

Read an Organisation Relationship Record by ID

HTTP request and Headers

GET {fhir-server}/OrganizationAffiliation?{id}

Authorization – {Bearer Token}

Parameters

The organisation relationship ID

  • {id}
  • e.g. 256248

HTTP Response Body

Outcome Response
Record Found OrganizationAffiliation - Example - OrganizationAffiliation 256248
Invalid ID OperationOutcome - Example - Error - Invalid ID

Query for an Organisation Relationship Record using Search Parameters

HTTP request and Headers

GET {fhir-server}/OrganizationAffiliation?

Authorization – {Bearer Token}

Parameters

active – a boolean flag for active only or inactive only organisation relationships

  • active={active}
  • e.g. active=True

primary-organization - The ‘source’ organisation which has a relationship. Referred to as the SourceOrganisation in the ORD schema. Must be a valid Organisation id with relationships to return results

  • primary-organization={primary-organisation}
  • e.g. primary-organization=https://fhir.nhs.uk/Id/ods-organization-code|G81086

participating-organization - The ‘Target’ or related organisation. Referred to as the TargetOrganisation in the ORD schema. Must be a valid Organisation id.

  • participating-organization={participating-organisation}
  • e.g. participating-organization=https://fhir.nhs.uk/Id/ods-organization-code|4VE03

_include - enables you return related resources.
For example:
OrganizationAffiliation:primary-organization will include Organization resource records for the SourceOrganisations in the search results
OrganizationAffiliation:participating-organization will include Organization resource records for all the TargetOrganisations in the search results

  • _include={include}
  • e.g. _include=OrganizationAffiliation:primary-organization

HTTP Response Body

Outcome Response
Record Found Bundle - Example - OrganizationAffiliation Search Result
_include Usage Bundle - Example - _include Search Result
No Records Found Bundle - Example - No Relationship Search Results Found