# This is an OpenAPI Specification (https://swagger.io/specification/) # for organisation-data-service-fhir-api owned by NHS Digital (https://digital.nhs.uk/) openapi: '3.0.0' info: title: 'organisation-data-terminology-api' version: '1.0.1-alpha' contact: name: 'ODS FHIR API Support' url: 'https://digital.nhs.uk/developer/help-and-support' email: api.management@nhs.net description: | ## Overview Use this API to access a dataset of health and social care organisations, such as trusts or GP practices, using the [Organisation Data Service (ODS)](https://digital.nhs.uk/services/organisation-data-service). The FHIR API contains the majority of ODS Content, including Organisations, practitioners and geographic information. It contains all the content found within the [ODS ORD API](http://digital.nhs.uk/developer/api-catalogue/organisation-data-service-ord) and the [ODS STU3 API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-service-fhir) ODS holds information for many different types of organisation related to health and social care – mostly in England but also other countries depending on the type of Organisation. For the full scope of data coverage of the ODS APIs, see [Organisation Data Service - data coverage](https://digital.nhs.uk/services/organisation-data-service/ods-data-coverage). Every organisation in ODS has a unique identifier called an ODS code. Using this API, you can: - search for an organisation to find its ODS code - get organisation details for a given ODS code - get details of related organisations - search for a practitioner to find their ODS code - get practitioner details for a given ODS code - get geographic boundaries for a postcode - get details of recently deleted or partially deleted records You can also limit the number of results returned, or just request a count of the number of search results. This FHIR API makes use of the Organization and OrganizationAffiliation FHIR resources plus range of CodeSystems to deliver the full suite of data, which you will use will depend on your need. ### Organisation Data We have been able to align the majority of data we hold for an organisation into the FHIR resources Organization and OrganizationAffiliation, through the limited use of extensions, however some previously available information could not be included. To access the Organisation attributes which are not included in the Organization resource use the ods-organization-code CodeSystem. The CodeSystem resource returns the following additional information: - organisation – Assigning Authority - related entities, the current related entity of any supported relationships - succession - any predecessors and/or successors and a flag to indicate the successor has also been succeeded - geographic - the appropriate mapping from the postcode dataset including Local Authority, Integrated Care Board or Lower Super Output Area (LSOA) ### Practitioner Data ODS publishes a limited set of prescribers held by the Business Services Authority, which includes General Practitioners and Nurse Prescribers, alongside Hospital and Dental Consultants provided by the workforce census returns. These codes have not been made available within the Pracitioner Resource as it is felt thet they do not accurately represent an indindiual, but rather reflect their prescribing activities. To access the Practitioner data you will need to use the practitioner CodeSystem in conjunction with the practitioner-relationship-instance CodeSystem which contians the relationship between a practitioner and the organisation at which they work. ### Postcodes and geographic boundaries available For every postcode within the NHS Postcode Directory, we have compiled a CodeSystem which contains the postcode along with its key Health and Social Care boundaries, including, Primary Care Organisations, Integrated Care Boards, Local Authority 2011 Lower Super Output Areas (LSOA11), Cancer Alliances and NHS England Regions ### CodeSystems to support the full range of ODS Content In Addition to the ods-organisation-code CodeSystem mentioned above, there are also CodeSystems for: - practitioner - includes details about related organisation (where a practitioner is based/works) and type of practitioner - postcode - contains various geographic values/boundaries for a postcode including which Lower Super Output Area, Parliamentary Constituency, Local Authority and Integrated Care Board boundary a postcode falls within - organization-relationship-instance – contains historic and current relationships - organization-role-instance – contains historic and current role instances - practitioner-role – contains the role a practitioner performs (currently limited to prescriber types/roles and consultants) - practitioner-relationship-instance – contains the associations between Prescribers (GPs) and GP Practices only - ODSOrganisationRole – reference Data for Primary and Non Primary Roles (Role ID, Role Name, and Primary/Non Primary indicator) - ODSRelationship – reference data for Relationships (Relationship Type ID and Relationship Name) - ODSRecordClass – reference data for record classes ie org or site - ODSRecordUseType – reference data for the type of use – Full for current records, refOnly for minimal records included for referential integrity - geography-name – reference data for ONS identifiers used within the Postcode CodeSystem

For a non-technical overview of how to build software that deals with organisations and healthcare services, see Building healthcare software - organisations and healthcare services.

## Who can use this API There are no particular restrictions on what this API can be used for. It can be used free of charge by public sector organisations in England, Scotland and Wales, including the NHS. This includes use by software developers building software for the public sector. ## Related APIs The following APIs also gives access to the Organisation Data Service: - [ODS Organisation Reference Data (ORD) API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-service-ord) - a richer version conforming to DCB000090 Standard, soon to be deprecated. - [ODS Organisation Reference Data (FHIR - STU3) API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-service-fhir) - STU3 version contains a minimal organization record, soon to be deprecated. ## API status and roadmap This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). To see our roadmap, or to suggest, comment or vote on features for this API, see our [interactive product backlog](https://nhs-digital-api-management.featureupvote.com/?order=popular&filter=allexceptdone&tag=ods-api#controls). If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support). ## Service level This API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm), Monday to Friday excluding bank holidays. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). ## Technology This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest). It also conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange. Specifically to FHIR R4 (v4.0.1), we have been working closely with the Interoperability team to develop and publish [Implementation guidance](https://simplifier.net/guide/organisation-data-services). You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular: - resource names are capitalised, singular and in American English, for example `/Organization` not `/organisations` - array names are singular, for example `line` not `lines` for address lines - data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object There are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration. ## Network access This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network). For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis). ## Security and authorisation ### Application-restricted access #### still to be decided This API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user. ## Errors We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range: - 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action - 400 to 499 if it failed because of a client error by your application - 500 to 599 if it failed because of an error on our server Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. ## Environments and testing | Environments | Base URLs | | ----------------- | ---------------------------------------------------------------------- | | User acceptance test (UAT) |TBC | | Production |TBC | For example: `TBC/fhir/Organization/RJY` returns the dataset for the organisation whose ODS code is RJY. ### Integration testing You can use the UAT environment to perform your integration testing. ## Onboarding #### still to be decided if we use the Term server Individual users can access content on the NHS England Terminology Server(ODS Instance) with a registered account. Shrimp is a terminology browser that is freely available on the internet, but it is only for browsing the content. The Terminology Server does not come with a built-in browser, so Shrimp is given as an example of a browsing tool, freely accessible on the internet. Other browsers can be used. If you are interested in integrating a software application with the Terminology Server, or if you want to [syndicate content to your own Terminology Server](https://digital.nhs.uk/services/terminology-server#syndication), you will need to complete a [system-to-system request form]https://digital.nhs.uk/services/terminology-server/system-to-system-account-request-form. servers: - url: 'https://beta.ods.dc4h.link/fhir/' description: User acceptance test (UAT) environment. - url: 'https://jenkins.ods.dc4h.link/fhir/' description: Production environment. paths: /Organization: get: summary: Search for an organisation operationId: get-organization-resources description: | ## Overview Use this endpoint to search for organisations or sites. Site codes which are supported for certain organisations can also be accessed here, there is no separate endpoint for sites. A FHIR Organization resource will be provided for each search result. You can search for information about an organisation using one or more of their: * ODS code * last change date * name * active or inactive status * address, city or postcode * organisation's primary role using RoleID, such as RO197 (NHS Trust) or RO167 (Optical Site) * organisation's non-primary role using RoleID, such as RO7 (Hospice) or RO318 (Integrated Care Board) This API returns the following details for an organisation: * organisation - ODS code, name, last change date, status if active or inactive , record class (organisation or site), record use type; A complete record or a reduced record included solely for referential integrity. * address - house or flat number, line 1, line 2, line 3, town, postcode, Unique Property Reference Number (UPRN) and country * contacts - website and telephone (where available) * roles - primary and non-primary roles including legal and operational start and end dates You can also request any related relations resources using the `_revinclude` parameter to return an OrganizationAffiliation Resource. You can try out the sandbox using the 'Try this API' feature on this page. (Coming Soon!) Alternatively, you can try out the sandbox using our Postman collection (placeholder link): [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747) parameters: - in: query name: _id description: | The organisation’s ODS code. If you already know the ODS code, use the `Get organisation details` endpoint instead. required: false schema: type: string example: 'RR8' - in: query name: identifier description: | The organisation's ODS code. This parameter is similar to `_id` but can also explicitly include the CodeSystem for the ID - which must be `ods-organization-code`. It's included for FHIR compatibility. required: false schema: type: string examples: without-code-system: summary: 'A search using just the ID:' value: 'G81086' with-code-system: summary: 'A search using the code system and ID:' value: 'https://fhir.nhs.uk/Id/ods-organization-code|G81086' - in: query name: lastChangeDate description: The date that the organisation record was last modified by ODS. Supports greater than, less and equal to. Can be compounded. required: false schema: type: string examples: greater-than: summary: 'Search for changes made after a date' value: 'gt2017-04-01' less-than: summary: 'Search for changes made before a date' value: 'lt2017-04-01' equal-to: summary: 'Search for changes made on a single date' value: '2024-02-06' - in: query name: name description: | The start of the organisation's name. For example, `Leeds` would match `Leeds Chest Clinic` but not `South Leeds Clinical Assessment Service`. To search anywhere in the organisation's name, use `name:contains`. To search for an exact match, use `name:exact`. Not case sensitive. Search expressions must: - contain a minimum of 3 characters and a maximum of 100 characters - only include the following characters: A-Z a-z 0-9 &()’+-_./:@ 'Space' required: false schema: type: string example: 'Leeds' - in: query name: name:contains description: | Any part of the organisation's name. For example, `Leeds` would match `Leeds Chest Clinic` and `South Leeds Clinical Assessment Service`. Not case sensitive. Search expressions must: - contain a minimum of 3 characters and a maximum of 100 characters - only include the following characters: A-Z a-z 0-9 &()’+-_./:@ 'Space' required: false schema: type: string example: 'Leeds' - in: query name: name:exact description: | The exact organisation name. Case sensitive. Search expressions must: - contain a minimum of 3 characters and a maximum of 100 characters - only include the following characters: A-Z a-z 0-9 &()’+-_./:@ 'Space' required: false schema: type: string example: 'LEEDS TEACHING HOSPITALS NHS TRUST' - in: query name: active description: Whether the organisation's record is still in active use. required: false schema: type: boolean example: 'true' - in: query name: address-postalcode description: | The start of the organisation's postcode. To search anywhere in the postcode, use `address-postalcode:contains`. To search for an exact match, use `address-postalcode:exact`. Not case sensitive. Search expressions must: - contain a minimum of 2 characters - only include alphanumeric characters and spaces required: false schema: type: string example: 'LS1' - in: query name: address-postalcode:contains description: | Any part of the organisation's postcode. Not case sensitive. Search expressions must: - contain a minimum of 2 characters - only include alphanumeric characters and spaces required: false schema: type: string example: '4DZ' - in: query name: address-postalcode:exact description: | The exact organisation postcode. Case sensitive. Search expressions must: - contain a minimum of 2 characters - only include alphanumeric characters and spaces required: false schema: type: string example: 'LS1 4DZ' - in: query name: address-city description: | The start of the organisation's city address. To search anywhere in the city address, use `address-city:contains`. To search for an exact match, use `address-city:exact`. Not case sensitive. Search expressions must: - contain a minimum of 2 characters - only include alphanumeric characters and spaces required: false schema: type: string example: 'Derby' - in: query name: address-city:contains description: | Any part of the organisation's city address. Not case sensitive. Search expressions must: - contain a minimum of 2 characters - only include alphanumeric characters and spaces required: false schema: type: string example: 'Derby' - in: query name: address-city:exact description: | The exact organisation city address. Case sensitive. Search expressions must: - contain a minimum of 2 characters - only include alphanumeric characters and spaces required: false schema: type: string example: 'DERBY' - in: query name: address-country description: | The start of the organisation's country. Not case sensitive. To search anywhere in the country address, use `address-country:contains`. To search for an exact match, use `address-country:exact`. Search expressions must: - contain a minimum of 2 characters - only include alphanumeric characters and spaces required: false schema: type: string example: 'ENGLAND' - in: query name: roleCode description: | The organisation's role, based on the `ODSOrganisationRole` CodeSystem. An organisation in ODS can have one or many roles. To exclude organisations with a specific role use `roleCode:not` To search for organisations that have multiple roles (like an 'AND' operator), include the `roleCode` query parameter multiple times. To search for organisations that have one of several roles (like an 'OR' operator), use a comma separator. You may combine 'AND' and 'OR' searches. To discover whether a role is primary or non-primary, refer to the `ODSOrganisationRelationship` CodeSystem required: false schema: type: string examples: without-code-system: summary: 'A search using just the role code (RO197 = NHS trust):' value: 'RO197' with-code-system: summary: 'A search using the code system and role code:' value: 'https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole|RO197' multiple-roles: summary: "A search for multiple roles (like an 'OR' operator):" value: 'RO197,RO198' coumpound-roles: summary: "A search for combined roles (like an 'AND' operator):" value: 'roleCode=RO197&roleCode=RO7' - in: query name: roleCode:not description: | Exclude organisations from the search results based on their role required: false schema: type: string examples: compound: summary: 'A search combining roleCode and roleCode:not' value: 'roleCode=RO177&roleCode:not=RO76' single: summary: 'A search using the code system and role code:' value: 'roleCode:not=https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole|RO197' - in: query name: activeRoleCode description: | Searches only active roles within the `ODSOrganisationRole` CodeSystem To exclude organisations with a specific role use `activeRoleCode:not` To search for organisations that have multiple roles (like an 'AND' operator), include the `activeRoleCode` query parameter multiple times. To search for organisations that have one of several roles (like an 'OR' operator), use a comma separator. You may combine 'AND' and 'OR' searches. To discover whether a role is primary or non-primary, refer to the `ODSOrganisationRelationship` CodeSystem required: false schema: type: string examples: without-code-system: summary: 'A search using just the role code (RO197 = NHS trust):' value: 'RO197' with-code-system: summary: 'A search using the code system and role code:' value: 'https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole|RO197' multiple-roles: summary: "A search for multiple roles (like an 'OR' operator):" value: 'RO197,RO198' - in: query name: _count description: Number of results to return. required: false schema: type: string example: '1000' - in: query name: _summary description: Return a count of the matching resources, without returning the actual matches. required: false schema: type: string enum: [count] - in: query name: _offset description: When used with _count, enables paging through large result sets required: false schema: type: string example: 2000 responses: '200': description: Valid request that returns a FHIR Organization resource(s) that match the search criteria (which may be 0). content: application/fhir+json: example: { "resourceType": "Bundle", "id": "d84a1a14-d90f-4dd7-a5bc-b5e56a81d1af", "meta": { "lastUpdated": "2024-03-14T11:03:31.163+00:00" }, "type": "searchset", "link": [ { "relation": "self", "url": "https://jenkins.ods.dc4h.link/fhir/Organization?_count=2&lastChangeDate=lt2023-05-04&lastChangeDate=gt2023-05-02" }, { "relation": "next", "url": "https://jenkins.ods.dc4h.link/fhir/Organization?_count=2&_offset=2&lastChangeDate=lt2023-05-04&lastChangeDate=gt2023-05-02" } ], "entry": [ { "fullUrl": "https://jenkins.ods.dc4h.link/fhir/Organization/AQN", "resource": { "resourceType": "Organization", "id": "AQN", "meta": { "versionId": "3", "lastUpdated": "2024-01-23T12:56:03.130+00:00", "source": "#df0974983053aca7", "profile": [ "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization", "https://fhir.nhs.uk/England/StructureDefinition/England-Organization-ODS" ] }, "extension": [ { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-OrganisationRole", "extension": [ { "url": "instanceID", "valueInteger": 233160 }, { "url": "roleCode", "valueCodeableConcept": { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO172", "display": "INDEPENDENT SECTOR HEALTHCARE PROVIDER" } ] } }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Legal", "display": "Legal" } }, { "url": "period", "valuePeriod": { "start": "2015-04-01" } } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Operational", "display": "Operational" } }, { "url": "period", "valuePeriod": { "start": "2015-04-01" } } ] }, { "url": "active", "valueBoolean": true } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedDateTime", "extension": [ { "url": "type", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-ODSDateTime", "code": "LastChangeDate", "display": "Last Change Date" } }, { "url": "dateTime", "valueDateTime": "2023-05-03" } ] } ], "identifier": [ { "use": "official", "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "AQN", "assigner": { "display": "HSCIC" } } ], "active": true, "type": [ { "coding": [ { "system": "https://fhir.nhs.uk/England/CodeSystem/England-ODSRecordUseType", "code": "Full", "display": "Full" } ] }, { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRecordClass", "code": "RC1", "display": "HSCOrg" } ] } ], "name": "PARTNERING HEALTH LIMITED", "address": [ { "line": [ "AILSA HOUSE 3 TURNBERRY HOUSE", "4400 PARKWAY", "WHITELEY" ], "city": "FAREHAM", "postalCode": "PO15 7FJ", "country": "ENGLAND" } ] }, "search": { "mode": "match" } }, { "fullUrl": "https://jenkins.ods.dc4h.link/fhir/Organization/C4O9I", "resource": { "resourceType": "Organization", "id": "C4O9I", "meta": { "versionId": "3", "lastUpdated": "2024-01-23T13:00:38.788+00:00", "source": "#b71fdedd3d5fad9e", "profile": [ "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization", "https://fhir.nhs.uk/England/StructureDefinition/England-Organization-ODS" ] }, "extension": [ { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-OrganisationRole", "extension": [ { "url": "instanceID", "valueInteger": 503768 }, { "url": "roleCode", "valueCodeableConcept": { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO181", "display": "PHARMACY HEADQUARTER" } ] } }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Legal", "display": "Legal" } }, { "url": "period", "valuePeriod": { "start": "2023-04-28" } } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Operational", "display": "Operational" } }, { "url": "period", "valuePeriod": { "start": "2023-04-28" } } ] }, { "url": "active", "valueBoolean": true } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedDateTime", "extension": [ { "url": "type", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-ODSDateTime", "code": "LastChangeDate", "display": "Last Change Date" } }, { "url": "dateTime", "valueDateTime": "2023-05-03" } ] } ], "identifier": [ { "use": "official", "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "C4O9I", "assigner": { "display": "NHS ENGLAND" } } ], "active": true, "type": [ { "coding": [ { "system": "https://fhir.nhs.uk/England/CodeSystem/England-ODSRecordUseType", "code": "Full", "display": "Full" } ] }, { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRecordClass", "code": "RC1", "display": "HSCOrg" } ] } ], "name": "WM BROWN (KINGSHURST) LIMITED", "address": [ { "extension": [ { "url": "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey", "extension": [ { "url": "type", "valueCodeableConcept": { "coding": [ { "system": "https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType", "code": "UPRN", "display": "Unique Property Reference Number" } ] } }, { "url": "value", "valueString": "100071397351" } ] } ], "line": [ "228-230 WYCHALL ROAD" ], "city": "BIRMINGHAM", "postalCode": "B31 3AU", "country": "ENGLAND" } ] }, "search": { "mode": "match" } } ] } application/fhir+xml: example: |
'4XX': description: | An error occurred as follows: | HTTP Code | issue.severity | issue.code | issue.details.code | issue.details.display | |------------ |----------------|---------------|---------------------|--------------------- | |400 |error |invalid |HAPI-1940 |Invalid Date/Time/Quantity format | |400 |error |invalid |HAPI-0524 |Unknown Search Parameter| |404 |error |invalid |HAPI-2001 |Organization not found | |405 |error |method not allowed|HAPI-0427 |Method Not Allowed | content: application/fhir+json: example: { "resourceType": "OperationOutcome", "text": { "status": "generated", "div": "

Operation Outcome

ERROR[]HAPI-0524: Unknown search parameter "count" for resource type "Organization". Valid search parameters for this search are: [_content, _id, _lastUpdated, _profile, _security, _source, _tag, _text, active, activeRoleCode, address, address-city, address-country, address-postalcode, address-state, address-use, endpoint, identifier, lastChangeDate, name, partof, phonetic, roleCode, type]
" }, "issue": [ { "severity": "error", "code": "processing", "diagnostics": "HAPI-0524: Unknown search parameter \"count\" for resource type \"Organization\". Valid search parameters for this search are: [_content, _id, _lastUpdated, _profile, _security, _source, _tag, _text, active, activeRoleCode, address, address-city, address-country, address-postalcode, address-state, address-use, endpoint, identifier, lastChangeDate, name, partof, phonetic, roleCode, type]" } ] } application/xml: example: |

Operation Outcome

ERROR [] HAPI-0524: Unknown search parameter "count" for resource type "Organization". Valid search parameters for this search are: [_content, _id, _lastUpdated, _profile, _security, _source, _tag, _text, active, activeRoleCode, address, address-city, address-country, address-postalcode, address-state, address-use, endpoint, identifier, lastChangeDate, name, partof, phonetic, roleCode, type]
/Organizationaffiliation: get: summary: Search for a relationship operationId: get-organizationaffiliation-resources description: | ## Overview Use this endpoint to search for relationship records. Most commonly you would use this endpoint to get all the relationships for a given organisation, based on its ODS code. For relationships, this API returns the following details: * related organisation ODS code * relationship type and relationship name * relationship legal start and end dates * relationship operational start and end dates you can search using various combinations of: * Primary-Organisation - known within the ORD products as the Source Organisation * Participating-Organisation - known within the ORD products as the Target Organisation * relationship status It is also possible to return the relevant Organization Resources in these searches using the `_include` parameter parameters: - in: query name: _id description: | The organisation's ID - also known as its ODS code. If you already know the ODS code, consider using the 'Get organsiation details' endpoint instead. required: false schema: type: string example: 'RTG' - in: query name: primary-organisation description: | The ‘source’ organisation which has a relationship. referred to as the SourceOrganisation in the ORD schema Must be a valid Organisation code with relationships to return results required: false schema: type: string example: 'G81086' - in: query name: participating-organization description: | The ‘Target’ or related organisation. Referred to as the Target Organisation in the ORD schema Must be a valid Organisation code with relationships to return results required: false schema: type: string example: '97R' - in: query name: active description: Whether the organisation's relationship record is still in active use. required: false schema: type: boolean example: 'true' - in: query name: _count description: Number of results to return. required: false schema: type: string example: '1000' - in: query name: _include description: | Enables you return related resources. OrganizationAffiliation:primary-organization will include Organization resource records for the ‘Source’ Organisations in the search results OrganizationAffiliation:participating-organization will include Organization resource records for all the ‘Target’ Organisations in the search results you can include both primary and participating organization resources by including multiple `_include` parameters required: false schema: type: string examples: primary-organization: summary: Include primary-organization value: OrganizationAffiliation:primary-organization participating-Organization: summary: Include participating-organization value: OrganizationAffiliation:participating-organization - in: query name: _summary description: Return a count of the matching resources, without returning the actual matches. required: false schema: type: string enum: [count] responses: '200': description: Valid request that returns any FHIR OrganizationAffiliation resources that match the search criteria (which may be 0). content: application/fhir+json: example: { "resourceType": "Bundle", "id": "3a286c55-83c9-4869-aaf1-c69186656ade", "meta": { "lastUpdated": "2024-03-15T10:47:18.746+00:00" }, "type": "searchset", "total": 3, "link": [ { "relation": "self", "url": "https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation?primary-organization=FDC49" } ], "entry": [ { "fullUrl": "https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation/383689", "resource": { "resourceType": "OrganizationAffiliation", "id": "383689", "meta": { "versionId": "3", "lastUpdated": "2024-01-23T15:40:47.090+00:00", "source": "#72eb666ff3d30383", "profile": [ "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation", "https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS" ] }, "extension": [ { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Legal", "display": "Legal" } }, { "url": "period", "valuePeriod": { "start": "2015-05-11", "end": "2020-03-31" } } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Operational", "display": "Operational" } }, { "url": "period", "valuePeriod": { "start": "2015-05-11", "end": "2020-03-31" } } ] } ], "identifier": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance", "value": "383689" } ], "active": false, "period": { "start": "2015-05-11", "end": "2020-03-31" }, "organization": { "reference": "Organization/FDC49", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "FDC49" } }, "participatingOrganization": { "reference": "Organization/Q72", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "Q72" } }, "code": [ { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship", "code": "RE5", "display": "IS LOCATED IN THE GEOGRAPHY OF" } ] } ] }, "search": { "mode": "match" } }, { "fullUrl": "https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation/648449", "resource": { "resourceType": "OrganizationAffiliation", "id": "648449", "meta": { "versionId": "3", "lastUpdated": "2024-01-23T17:00:12.326+00:00", "source": "#033821a3d00d51fe", "profile": [ "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation", "https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS" ] }, "extension": [ { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Legal", "display": "Legal" } }, { "url": "period", "valuePeriod": { "start": "2020-04-01", "end": "2020-09-22" } } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Operational", "display": "Operational" } }, { "url": "period", "valuePeriod": { "start": "2020-04-01", "end": "2020-09-22" } } ] } ], "identifier": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance", "value": "648449" } ], "active": false, "period": { "start": "2020-04-01", "end": "2020-09-22" }, "organization": { "reference": "Organization/FDC49", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "FDC49" } }, "participatingOrganization": { "reference": "Organization/QWO", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "QWO" } }, "code": [ { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship", "code": "RE5", "display": "IS LOCATED IN THE GEOGRAPHY OF" } ] } ] }, "search": { "mode": "match" } }, { "fullUrl": "https://jenkins.ods.dc4h.link/fhir/OrganizationAffiliation/716945", "resource": { "resourceType": "OrganizationAffiliation", "id": "716945", "meta": { "versionId": "3", "lastUpdated": "2024-01-23T17:23:48.733+00:00", "source": "#8e8ca746678177d7", "profile": [ "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation", "https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS" ] }, "extension": [ { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Legal", "display": "Legal" } }, { "url": "period", "valuePeriod": { "start": "2020-09-23" } } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Operational", "display": "Operational" } }, { "url": "period", "valuePeriod": { "start": "2020-09-23" } } ] } ], "identifier": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance", "value": "716945" } ], "active": true, "period": { "start": "2020-09-23" }, "organization": { "reference": "Organization/FDC49", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "FDC49" } }, "participatingOrganization": { "reference": "Organization/QF7", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "QF7" } }, "code": [ { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship", "code": "RE5", "display": "IS LOCATED IN THE GEOGRAPHY OF" } ] } ] }, "search": { "mode": "match" } } ] } '4XX': description: | An error occurred as follows: | HTTP Code | issue.severity | issue.code | issue.details.code | issue.details.display | |------------ |----------------|---------------|---------------------|--------------------- | |400 |error |invalid |HAPI-1940 |Invalid Date/Time/Quantity format | |400 |error |invalid |HAPI-0524 |Unknown Search Parameter| |404 |error |invalid |HAPI-2001 |Organization not found | |405 |error |method not allowed|HAPI-0427 |Method Not Allowed | content: application/fhir+json: example: { "resourceType": "OperationOutcome", "id": "82c75580-1702-469e-aec1-43034b48f060", "meta": { "profile": "https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1" }, "issue": [ { "severity": "error", "code": "invalid", "details": { "coding": { "system": "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1", "code": "INVALID_PARAMETER", "display": "Invalid parameter" } }, "diagnostics": "Unknown argument found - nam" } ] } /Organization/{id}: get: summary: Get organisation details operationId: get-single-organization description: | ## Overview Use this endpoint to get details for a single organisation based on its ODS code. Site codes which are supported for certain organisations can also be accessed here, there is not a separate endpoint for sites. A FHIR Organization resource will be provided when a valid id has been provided. ## What is included This API returns the following details for an organisation: * organisation - ODS code, name, last change date, status if active or inactive , record class (organisation or site), record use type; A complete record or a reduced record included solely for referential integrity. * address - house or flat number, line 1, line 2, line 3, town, postcode, Unique Property Reference Number (UPRN) and country * contacts - website and telephone (where available) * roles - primary and non-primary roles including legal and operational start and end dates To access a richer Organisation dataset, use the ods-organization-code CodeSystem, when searching the CodeSystem resource with an ODS Code, in addition to the above, the following will also be returned: * organisation –Assigning Authority * related entities, the current related entity of any supported relationships * succession - any predecessors and/or successors and a flag to indicate the successor has also been succeeded * geographic - the appropriate mapping from the postcode dataset including Local Authority, Integrated Care Board or Lower Super Output Area (LSOA) parameters: - in: path name: id description: | The organisation's ODS code. required: true schema: type: string example: 'RR8' responses: '200': description: Valid request that returns a FHIR Organisation resource content: application/fhir+json: example: { "resourceType": "Organization", "id": "RR8", "meta": { "versionId": "4", "lastUpdated": "2024-01-23T13:37:16.122+00:00", "source": "#42f81a2818154581", "profile": [ "https://fhir.nhs.uk/England/StructureDefinition/England-Organization-ODS", "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization" ] }, "extension": [ { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-OrganisationRole", "extension": [ { "url": "instanceID", "valueInteger": 37525 }, { "url": "roleCode", "valueCodeableConcept": { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO197", "display": "NHS TRUST" } ] } }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Legal", "display": "Legal" } }, { "url": "period", "valuePeriod": { "start": "1998-04-01" } } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Operational", "display": "Operational" } }, { "url": "period", "valuePeriod": { "start": "1998-04-01" } } ] }, { "url": "active", "valueBoolean": true } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedDateTime", "extension": [ { "url": "type", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-ODSDateTime", "code": "LastChangeDate", "display": "Last Change Date" } }, { "url": "dateTime", "valueDateTime": "2023-11-14" } ] } ], "identifier": [ { "use": "official", "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "RR8", "assigner": { "display": "HSCIC" } } ], "active": true, "type": [ { "coding": [ { "system": "https://fhir.nhs.uk/England/CodeSystem/England-ODSRecordUseType", "code": "Full", "display": "Full" } ] }, { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRecordClass", "code": "RC1", "display": "HSCOrg" } ] } ], "name": "LEEDS TEACHING HOSPITALS NHS TRUST", "telecom": [ { "system": "phone", "value": "0113 243 3144" }, { "system": "url", "value": "HTTPS://WWW.LEEDSTH.NHS.UK/" } ], "address": [ { "extension": [ { "url": "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey", "extension": [ { "url": "type", "valueCodeableConcept": { "coding": [ { "system": "https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType", "code": "UPRN", "display": "Unique Property Reference Number" } ] } }, { "url": "value", "valueString": "72016246" } ] } ], "line": [ "ST. JAMES'S UNIVERSITY HOSPITAL", "BECKETT STREET" ], "city": "LEEDS", "postalCode": "LS9 7TF", "country": "ENGLAND" } ] } application/xml: example: |
'404': description: | Invalid ODS Code provided, will return a 404 Not Found error content: application/fhir+json: example: { "resourceType": "OperationOutcome", "text": { "status": "generated", "div": "

Operation Outcome

ERROR[]HAPI-2001: Resource Organization/8J632648493 is not known
" }, "issue": [ { "severity": "error", "code": "processing", "diagnostics": "HAPI-2001: Resource Organization/8J632648493 is not known" } ] } /OrganizationAffiliation/{id}: get: summary: Get relationship details operationId: get-single-organizationaffiliation description: | ## Overview Use this endpoint to a retrieve a single relationship record based on its unique identifier. This record describes a relationship between a pair of organisations. The types of relationships which an organisation may have will vary depending on the primary role of the organisation. In some case there may be multiple relationships between the same two organisations, each having a different relationship type. A FHIR OrganizationAffiliation Resource will be returned when a valid id is provided. parameters: - in: path name: id description: | The relationship ID. required: true schema: type: string example: '617400' responses: '200': description: Valid request that returns a FHIR OrganizationAffiliation resource content: application/fhir+json: example: { "resourceType": "OrganizationAffiliation", "id": "617400", "meta": { "versionId": "3", "lastUpdated": "2024-01-23T16:51:55.472+00:00", "source": "#25caee48b2ce3432", "profile": [ "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation", "https://fhir.nhs.uk/England/StructureDefinition/England-OrganizationAffiliation-ODS" ] }, "extension": [ { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Legal", "display": "Legal" } }, { "url": "period", "valuePeriod": { "start": "2019-10-01" } } ] }, { "url": "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-TypedPeriod", "extension": [ { "url": "dateType", "valueCoding": { "system": "https://fhir.nhs.uk/England/CodeSystem/England-PeriodType", "code": "Operational", "display": "Operational" } }, { "url": "period", "valuePeriod": { "start": "2019-10-01" } } ] } ], "identifier": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance", "value": "617400" } ], "active": true, "period": { "start": "2019-10-01" }, "organization": { "reference": "Organization/G81086", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "G81086" } }, "participatingOrganization": { "reference": "Organization/U36842", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "U36842" } }, "code": [ { "coding": [ { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship", "code": "RE8", "display": "IS PARTNER TO" } ] } ] } application/xml: example: | '404': description: | Invalid ODS Code provided, will return a 404 Not Found error content: application/fhir+json: example: { "resourceType": "OperationOutcome", "text": { "status": "generated", "div": "

Operation Outcome

ERROR[]HAPI-2001: Resource Organization/8J632648493 is not known
" }, "issue": [ { "severity": "error", "code": "processing", "diagnostics": "HAPI-2001: Resource Organization/8J632648493 is not known" } ] } /List{id}: get: summary: Get deletion notices operationId: get-deletion-notices description: | ## Overview Use this endpoint to check for any full record or partial record deletions. As these occur infrequently a full List of deletions will be provided. There are four Lists which provide details of deletions that have occured within the ODS Data * Organization-deletion * OrganizationAffiliation-deletion * Organization-role-deletion * Organization-succession-deletion #### Organization-deletion From time to time it is posible that we create or receive orgnisations which are created in error and removed from the source data. when this occurs there is no updates to the record, it is simply no longer available. to inform users when Organisations have been deleted, we have used the List resource to provide the ODS Code of the records which have been deleted so that you may removed them from any local copies you may be maintaining. #### OrganizationAffilliation-deletion in the unlikely event that a relationship must be deleted rather then given an end date, the RelationshipID will be provided in this List resource. #### Organization-role-deletion In the unlikely event that a role is deleted, rather than given an end date, the roleID will be provided in this list resource. As the role forms part of the Organization Resource you may not need to take action other than to verify the role was intentionally removed. #### Organization-succession-deletion In the unlikely event that the succession is removed from an organisation, the Organisation's ODS Code and that of it's successor will be published in this list resource. As the successor and predecessor are properties of the ods-organization-code CodeSystem, you may not need to take action if you are maintaining a local copy of the CodeSystem other than to verify the succession was intentionally removed. parameters: - in: path name: id description: | the business name for the List which contains details of deleted records required: true schema: type: string example: 'Organization-deletion' responses: '200': description: a valid List resource containing details of deleted records content: application/fhir+json: example: { "resourceType": "List", "id": "Organization-deletion", "meta": { "versionId": "3", "lastUpdated": "2024-03-06T08:33:55.775+00:00", "source": "#3c8d0fc7e6526ce0" }, "status": "current", "mode": "working", "title": "List of Organization Resource Deletions", "date": "2024-01-25T00:00:00+00:00", "note": [ { "text": "A list of complete Organisation records which have been deleted from the ODS Dataset" } ], "entry": [ { "date": "2024-01-17T00:00:00+00:00", "item": { "type": "Organization", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "FVG57" } } }, { "date": "2024-01-17T00:00:00+00:00", "item": { "type": "Organization", "identifier": { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "value": "FJE57" } } } ] } application/xml: example: <date value="2024-01-25T00:00:00+00:00"/> <note> <text value="A list of complete Organisation records which have been deleted from the ODS Dataset"/> </note> <entry> <date value="2024-01-17T00:00:00+00:00"/> <item> <type value="Organization"/> <identifier> <system value="https://fhir.nhs.uk/Id/ods-organization-code"/> <value value="FVG57"/> </identifier> </item> </entry> <entry> <date value="2024-01-17T00:00:00+00:00"/> <item> <type value="Organization"/> <identifier> <system value="https://fhir.nhs.uk/Id/ods-organization-code"/> <value value="FJE57"/> </identifier> </item> </entry> </List> /CodeSystem/: get: summary: Search for additional instance and reference data operationId: search-codesystem description: | ## Overview Use this endpoint to access a range of information contained in CodeSystems to meet your needs. We have CodeSystems that contain regularly changing data such as organisations, practitioners and relationships plus more traditional reference based CodeSystems. CodeSystem names include the date when they were last updated i.e. `ods-organization-code-2024-03-07` so when searching for individual concepts (records within the CodeSystem) it is necessary to perform a search using a `$lookup` providing the system and code required in addition to any properties you wish to return. For example: `/CodeSystem/$lookup?system=https://fhir.nhs.uk/Id/ods-organization-code&code=G81086&property=*` ### Summary information A summary of each codeSystem can be returned to see which properties are available and which search operations are supported, without attempting to return the data. organisation, role, relationship, postcode and geography information will all generate errors as they are too large to be returned. Performing a search will default to summary mode and list each instance of the CodeSystem currently stored on the Server. it is expected that we will retain 2-3 versions at any given point. For example: `/CodeSystem?url=https://fhir.nhs.uk/Id/ods-organization-code` The smaller reference based CodeSystems these can be retrieved in full using `_summary=false` which will return all versions stored on the server in full. For example: `/CodeSystem?system=https://digital.nhs.uk/services/organisation-data-service/CodeSystem/practitioner-role&_summary=false` ## Code Validation Using the $validate operation you can check whether a code is present within any given ValueSet and you can also provide additional properties to validate their values. For example: `CodeSystem/$validate-code?url=https://fhir.nhs.uk/Id/ods-organization-code&code=RH8&status=active` ## Organisation Data ### ods-organization-code https://fhir.nhs.uk/Id/ods-organization-code In addition to the data available through the FHIR Organization resource we also have the following properties: * related organisations using a Relationship ID such as RE4 (commissioned by), RE6 (operated by), RE8 is Partner to and Nomonated Payee for (RE10) * presence of successor or predecessor information * indicator for onward succession * geographic values such as Local Authority boundary, Integrated Care Board boundary or Lower Super Output Area (LSOA) ### organisation-relationship-instance https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance Contains relationship history ### organisation-role-instance Contains role history ## Practitioner Data ### practitioner https://digital.nhs.uk/services/organisation-data-service/CodeSystem/practitioner Contains the prescribing practitioner and consultants in a single CodeSystem to enable lookup and validation of Practitioner codes. Practitioners are categorised with a type and role. roles and types can be validated against the practitioner-role CodeSystem. Types include `PGP` (General Practitioner), `PNURSE` - Prescribing Nurse and `PDENTCON` Dental Consultants. Roles include `PHOSPCON120` (ear nose and throat), `PGP1` (principal GP), `PNURSE1` (district nurse / health visitor) Where practitioners are associated to an organisation, the current/latest values is held in a membership property, these include `ME1` Parent Practice for GPs and `ME4` Parent Trust for a Dental Consultant. More information about the associations can be found in the practitioner-relationship-instance CodeSystem. This CodeSystem has been designed to enable pracitioners with multiple codes, i.e a Prescribing Code and a General Medical Council (GMC) code to be returned or validated. Properties numbered from 1 to 8 contain a specific identifier issued by a range of authorities, more information about each assigned identifier including start date and issuing Authority can be found in the practitioner-additional-attribute CodeSystem ### practitioner-relationship-instance https://digital.nhs.uk/services/organisation-data-service/CodeSystem/practitioner-relationship-instance Contains relationship history where practitioners are associated with an organisation. ### practitioner-additional-attribute https://digital.nhs.uk/services/organisation-data-service/CodeSystem/practitioner-additional-attribute Contains additional information about the identifier issued to a practitioner, in addition to the identifier, the name and ODS code of the Issing authority, start and end dates for the identifier are included. ## Geographic Data #### https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name Supports the identification of Office for National Statistics (ONS) identifiers for geographic boundaries used within the ods-organization-code CodeSytem. ODS identifiers for geographic organisations such as `ICB` and `Local Authority` can be retreived from the `Organization` Endpoint. #### https://digital.nhs.uk/services/organisation-data-service/CodeSystem/postcode Contains every postcode within the NHS Postcode Directory and a selection of their geographic boundaries. More information about how this data is compiled can be found in the [NHSPD user guide](https://digital.nhs.uk/binaries/content/assets/website-assets/services/ods/user_guide.pdf). the following Geographic boundaries are included: * `CA` cancer alliance * `EW` electoral ward * `GOR` government office region * `ICB` integrated care board * `LA` local authority * `LSOA11` 2011 lower super output areas * `NHSER` NHS England region * `PC` parliamentary constituency * `PCO` primary care organisation * `SMHPC AED` strategic mental health provider collaborative - adult eating disorder * `SMHPC AS` strategic mental health provider collaborative - adult secure * `SMHPC CT4` strategic mental health provider collaborative - CYPMH tier 4 ## Reference Data #### https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole Every organisation has at least one role; a primary role. It may also have additional roles which provide more information about the organisation's function or purpose. The full list of role codes is contained in this CodeSystem and can be retreived in full or individual role codes can be returned or validated. This CodeSystem has 1 additional Property: `primaryRole` which contains a true/false value if the role is a primary role or not. #### https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRelationship Every relationship has a type to describe the nature of the relationship, which includes: `is Commissioned by`, `is operated by` and `is partner to`. #### https://digital.nhs.uk/services/organisation-data-service/CodeSystem/practitioner-role Within the former CSV publications for practitioners, any classifications against a practitioner such as consultant speciality code or nurse prescriber type have been converted to roles and can be returned or validated with this CodeSystem. parameters: - in: query name: system description: | The Unique Resource Indicator (URI) of the codesystem required: false schema: type: string examples: Organisation-Data: summary: ods-organization-code value: 'https://fhir.nhs.uk/Id/ods-organization-code' Relationship-Data: summary: organization-relationship-instance value: 'https://fhir.nhs.uk/Id/ods-organization-code' practitioner: summary: practitioner value: 'https://digital.nhs.uk/services/organisation-data-service/CodeSystem/practitioner' ODSOrganisationRole: summary: ODSOrganisationRole value: 'https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole' ODSRecordUseType: summary: ODSRecordUseType value: 'https://fhir.nhs.uk/England/CodeSystem/England-ODSRecordUseType' ODSRecordUseClass: summary: ODSRecordClass value: 'https://fhir.nhs.uk/England/CodeSystem/England-ODSRecordUseType' - in: query name: code description: | The code of the concept stored within the CodeSystem required: false schema: type: string example: 'G7112418' - in: query name: property description: | Include all or specific properties from a CodeSystem. To return all use asterisk ‘*’ To return multiple properties, include each one as a separate parameter required: false schema: type: string examples: return-all: summary: return all properties value: '*' return-one: summary: return a single property value: opStartDate - in: query name: _summmary description: | override default behaviour to retreive a subset of the CodeSystem content when searching. `data` and `false` will generate errors on larger CodeSystems. required: false schema: type: boolean example: false responses: '200': description: Valid request that returns every paramter for a single concept for the specified code. content: application/json: example: { "resourceType": "Parameters", "parameter": [ { "name": "code", "valueCode": "G81086" }, { "name": "display", "valueString": "BIRD-IN-EYE SURGERY" }, { "name": "name", "valueString": "ODS Organisation" }, { "name": "system", "valueUri": "https://fhir.nhs.uk/Id/ods-organization-code" }, { "name": "version", "valueString": "2024-03-07" }, { "name": "designation", "part": [ { "name": "use", "valueCoding": { "system": "http://terminology.hl7.org/CodeSystem/designation-usage", "code": "display" } }, { "name": "value", "valueString": "BIRD-IN-EYE SURGERY" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "status" }, { "name": "value", "valueCode": "active" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "RE4" }, { "name": "value", "valueCode": "97R" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "RE6" }, { "name": "value", "valueCode": "97R" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "RE8" }, { "name": "value", "valueCode": "U36842" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "inactive" }, { "name": "value", "valueBoolean": false }, { "name": "valueBoolean", "valueBoolean": false } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "country" }, { "name": "valueString", "valueString": "ENGLAND" }, { "name": "value", "valueString": "ENGLAND" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "opStartDate" }, { "name": "valueDateTime", "valueDateTime": "1974-04-01" }, { "name": "value", "valueDateTime": "1974-04-01" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "SMHPC CT4" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "B0N9F" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "B0N9F" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "LSOA11" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E01021221" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E01021221" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "uprn" }, { "name": "valueString", "valueString": "10091054340" }, { "name": "value", "valueString": "10091054340" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "town" }, { "name": "valueString", "valueString": "UCKFIELD" }, { "name": "value", "valueString": "UCKFIELD" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "postcode" }, { "name": "valueString", "valueString": "TN22 5AW" }, { "name": "value", "valueString": "TN22 5AW" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "telephone" }, { "name": "valueString", "valueString": "01825 763196" }, { "name": "value", "valueString": "01825 763196" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "NHSER" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "Y59" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "Y59" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "EW" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E05011661" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E05011661" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "SMHPC AS" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "H3F5A" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "H3F5A" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "name" }, { "name": "valueString", "valueString": "BIRD-IN-EYE SURGERY" }, { "name": "value", "valueString": "BIRD-IN-EYE SURGERY" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "PCO" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "97R" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "97R" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "role" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO177" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO177" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "role" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO76" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO76" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "SMHPC AED" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "R7G8O" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "R7G8O" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "primaryRole" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO177" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO177" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "assigningAuth" }, { "name": "valueString", "valueString": "NHS BUSINESS SERVICES AUTHORITY" }, { "name": "value", "valueString": "NHS BUSINESS SERVICES AUTHORITY" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "CA" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E56000012" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E56000012" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "address2" }, { "name": "valueString", "valueString": "FRAMFIELD ROAD" }, { "name": "value", "valueString": "FRAMFIELD ROAD" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "address1" }, { "name": "valueString", "valueString": "UCKFIELD COMMUNITY HOSPITAL" }, { "name": "value", "valueString": "UCKFIELD COMMUNITY HOSPITAL" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "lastChangeDate" }, { "name": "valueDateTime", "valueDateTime": "2023-08-22" }, { "name": "value", "valueDateTime": "2023-08-22" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "ICB" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "QNX" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "QNX" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "GOR" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "J" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "J" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "PC" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E14001023" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "E14001023" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "LA" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "815" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/geography-name", "code": "815" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "legStartDate" }, { "name": "valueDateTime", "valueDateTime": "1974-04-01" }, { "name": "value", "valueDateTime": "1974-04-01" } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "orgRecordClass" }, { "name": "valueCoding", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRecordClass", "code": "RC1" } }, { "name": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSRecordClass", "code": "RC1" } } ] }, { "name": "property", "part": [ { "name": "code", "valueCode": "refOnly" }, { "name": "valueBoolean", "valueBoolean": false }, { "name": "value", "valueBoolean": false } ] } ] } '4XX': description: | An error occurred as follows: | HTTP Code | issue.severity | issue.code | issue.details.code | issue.details.display | |------------ |----------------|---------------|---------------------|--------------------- | |400 |error |invalid |HAPI-1940 |Invalid Date/Time/Quantity format | |400 |error |invalid |HAPI-0524 |Unknown Search Parameter| |404 |error |invalid |HAPI-2001 |Organization not found | |405 |error |method not allowed|HAPI-0427 |Method Not Allowed | |422 |unprocessable |too-costly |Too many records requested (Use _count and _offset)|Invalid parameter | |422 |unprocessable |processing |No declared filter on Codesystem |An input field has an invalid value for its type | /ValueSet/: post: summary: Perform a ValueSet expansion operationId: search-ods-organization-code description: | ## Overview To retrieve a subset of records from an individual CodeSystem, you will need to perform a 'POST' operation, in which you will provide the details of the CodeSystem you are searching, along with any filters to be applied and properties you wish to include in the results. When you make a 'POST' operation, you perform an expansion on a ValueSet and provide a requestBody. The endpoint will return a successful (200) response code along with the search results, which may be an empty array if no records match your criteria. or an unsuccesful (4xx/5xx) response. requestBody: content: application/fhir+json: example: { "resourceType": "Parameters", "parameter": [ { "name": "valueSet", "resource": { "resourceType": "ValueSet", "compose": { "inactive": true, "include": [ { "system": "https://fhir.nhs.uk/Id/ods-organization-code", "filter": [ { "property": "lastChangeDate", "op": "=", "value": "gt2024-02-01" } ] } ] } } }, { "name": "activeOnly", "valueBoolean": false }, { "name": "property", "valueString": "primaryRole" }, { "name": "property", "valueString": "country" }, { "name": "count", "valueInteger": "2" } ] } responses: '200': description: a valid content: application/fhir+json: example: { "resourceType": "ValueSet", "expansion": { "identifier": "urn:uuid:7799a8c4-2d2a-4d74-b647-2d50aad98904", "timestamp": "2024-03-25T14:42:24+00:00", "total": 4725, "offset": 0, "parameter": [ { "name": "version", "valueUri": "https://fhir.nhs.uk/Id/ods-organization-code|2024-03-07" }, { "name": "used-codesystem", "valueUri": "https://fhir.nhs.uk/Id/ods-organization-code|2024-03-07" }, { "name": "activeOnly", "valueBoolean": false }, { "name": "count", "valueInteger": 2 } ], "contains": [ { "extension": [ { "url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property", "extension": [ { "url": "code", "valueCode": "primaryRole" }, { "url": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO104" } } ] }, { "url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property", "extension": [ { "url": "code", "valueCode": "country" }, { "url": "value", "valueString": "ENGLAND" } ] } ], "system": "https://fhir.nhs.uk/Id/ods-organization-code", "code": "AT32", "display": "FORGET ME NOT CARING LTD" }, { "extension": [ { "url": "http://ontoserver.csiro.au/profiles/expansion", "extension": [ { "url": "inactive", "valueBoolean": true } ] }, { "url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property", "extension": [ { "url": "code", "valueCode": "primaryRole" }, { "url": "value", "valueCoding": { "system": "https://digital.nhs.uk/services/organisation-data-service/CodeSystem/ODSOrganisationRole", "code": "RO172" } } ] }, { "url": "http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property", "extension": [ { "url": "code", "valueCode": "country" }, { "url": "value", "valueString": "ENGLAND" } ] } ], "system": "https://fhir.nhs.uk/Id/ods-organization-code", "inactive": true, "code": "AT9", "display": "SOUTH EAST LAMBETH HEALTH PARTNERSHIP" } ] } } '4XX': description: | An error occurred as follows: | HTTP Code | issue.severity | issue.code | issue.details.code | issue.details.display | |------------ |----------------|---------------|---------------------|--------------------- | |400 |error |invalid |HAPI-1940 |Invalid Date/Time/Quantity format | |400 |error |invalid |HAPI-0524 |Unknown Search Parameter| |404 |error |invalid |HAPI-2001 |Organization not found | |405 |error |method not allowed|HAPI-0427 |Method Not Allowed | |422 |unprocessable |too-costly |Too many records requested (Use _count and _offset)|Invalid parameter | |422 |unprocessable |processing |No declared filter on Codesystem |An input field has an invalid value for its type | /metadata: get: summary: Get capability statement operationId: get-capability-statement description: | ## Overview Use this endpoint to get a Capability Statement. A Capability Statement is a set of capabilities of a FHIR Server that may be used as a statement of actual server functionality or a statement of required or desired server implementation. [Needs updating] responses: '200': description: Retrieved the Capability Statement from the FHIR Server content: application/fhir+json: example: { "resourceType": "CapabilityStatement", "url": "https://uat.directory.spineservices.nhs.uk/STU3/metadata?", "version": "1.0.0", "name": "ODSAPI-CapabilityStatement-1", "status": "active", "date": "2018-04-12", "publisher": "NHS Digital", "contact": [ { "name": "National Service Desk", "telecom": [ { "system": "email", "value": "ssd.nationalservicedesk@nhs.net", "use": "work" }, { "system": "phone", "value": "0300 303 4034", "use": "work" } ] } ], "description": "An API for retrieving organisation data from the NHS Digital Organisation Data Service.", "copyright": "Copyright © 2017 NHS Digital", "kind": "instance", "instantiates": [ "https://fhir.nhs.uk/STU3/CapabilityStatement/ODSAPI-CapabilityStatement-1" ], "fhirVersion": "3.0.1", "acceptUnknown": "no", "format": [ "application/fhir+xml", "application/fhir+json" ], "implementationGuide": [ "https://developer.nhs.uk/apis/ods/" ], "profile": [ { "reference": "https://fhir.nhs.uk/STU3/StructureDefinition/ODSAPI-Organization-1" }, { "reference": "https://fhir.nhs.uk/STU3/StructureDefinition/ODSAPI-ActivePeriod-1" }, { "reference": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-ODSAPI-ActivePeriod-1" }, { "reference": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-ODSAPI-OrganizationRole-1" }, { "reference": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-ODSAPI-UPRN-1" }, { "reference": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-ODSAPI-DateType-1" } ], "rest": [ { "mode": "server", "security": { "cors": true }, "resource": [ { "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination", "extension": [ { "url": "required", "valueString": "ods-org-primaryRole" }, { "url": "required", "valueString": "ods-org-role" } ] } ], "type": "Organization", "profile": { "reference": "https://fhir.nhs.uk/STU3/StructureDefinition/ODSAPI-Organization-1" }, "interaction": [ { "code": "read" }, { "code": "search-type" } ], "versioning": "no-version", "readHistory": false, "updateCreate": false, "conditionalCreate": false, "conditionalRead": "not-supported", "conditionalUpdate": false, "conditionalDelete": "not-supported", "searchParam": [ { "name": "_id", "type": "token" }, { "name": "_lastUpdated", "type": "date" }, { "name": "_count", "type": "number" }, { "name": "_summary", "type": "token" }, { "name": "identifier", "type": "token" }, { "name": "name", "type": "string" }, { "name": "active", "type": "token" }, { "name": "address-city", "type": "string" }, { "name": "address-postalcode", "type": "string" }, { "name": "ods-org-role", "definition": "https://fhir.nhs.uk/STU3/SearchParameter/ODSAPI-OrganizationRole-Role-1", "type": "token" }, { "name": "ods-org-primaryRole", "definition": "https://fhir.nhs.uk/STU3/SearchParameter/ODSAPI-OrganizationRole-PrimaryRole-1", "type": "token" } ] }, { "type": "CodeSystem", "interaction": [ { "code": "read" } ], "versioning": "no-version", "readHistory": false, "updateCreate": false, "conditionalCreate": false, "conditionalRead": "not-supported", "conditionalUpdate": false, "conditionalDelete": "not-supported", "searchParam": [ { "name": "url", "type": "string", "documentation": "The logical URL for the CodeSystem" } ] } ] } ] }