openapi: 3.0.0 info: title: organisation-data-terminology-api version: '0.1' 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 and sites, such as trusts or GP practices, using the [Organisation Data Service (ODS)](https://digital.nhs.uk/services/organisation-data-service). This [FHIR](https://hl7.org/fhir/R4/organization.html) 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 or site to find its ODS code - get organisation details for a given ODS code - get details of related organisations and sites - get details of records changed in a given date range - 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 - limit the number of results returned - request a count of the number of search results This FHIR API can give you `Organization` and `OrganizationAffiliation` FHIR resources, or you can specify exactly what information you want to return with a wide range of CodeSystems. ### 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 2011 Lower Super Output Area (LSOA11) ### Practitioner data ODS publishes a limited set of prescribers held by the NHS Business Services Authority, which includes General Practitioners and Nurse Prescribers, alongside Hospital and Dental Consultants provided by the NHS England Workforce and Facilities team as an extract from the Electronic Staff Record system. These codes have not been made available within the Practitioner Resource as it is felt that they do not accurately represent an individual, 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 contains 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 (PCO), Integrated Care Boards (ICB), Local Authority (LA), 2011 Lower Super Output Areas (LSOA11), Cancer Alliances (CA) and NHS England Regions (NHSER). ### 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 - succession - succession (merger and acquisition) details for statutory organisations - 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 for example organisation 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 give access to the Organisation Data Service: - [ODS Organisation Reference Data (ORD) API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-service-ord) - a version conforming to DCB000090 Standard, under review for deprecation. - [ODS Organisation Reference Data (FHIR - STU3) API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-service-fhir) - Retired. ## API status and roadmap This API is [in production](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). To provide feedback or suggest developments for this API, use the [Developer Community](https://developer.community.nhs.uk/c/ods/21). Planned data model and product developments can be viewed via the [Organisation Data Service roadmap](https://digital.nhs.uk/services/organisation-data-service/ods-roadmap). ## Service level This API is a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). ## Rate limits The Organisation Data Terminology FHIR R4 API has been configured with a custom rate limit based on expected traffic patterns, use case and consumer profiles, and technical constraints. To ensure a good level of service users should aim to keep usage below 5,000 requests per 5 minutes. The API rate limit is greater than the default, baseline limit for APIM hosted APIs (5 calls per second). If a user or their application exceeds this rate limit, an HTTP status of 429 (Too Many Requests) will be received. For strategies on handling error codes, refer to [error handling guidance](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#error-handling). ## 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 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. To use this access mode, use the following security pattern: - [Application-restricted RESTful APIs - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication) ## 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. ### Payload (Response Size Limit) The API's response size limit is based on payload, not number of records returned. The payload limit is set to 10mb. If this limit is exceeded: - an error response with an HTTP status of 422 (Response exceeds APIM size limit) will be returned - the amount of data returned will need to be controlled using count and offset parameters Please [contact ODS](https://digital.nhs.uk/services/organisation-data-service/contact-the-organisation-data-service) for further advice if required. ## Open Source You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful: | Resource | Description | Links | |---------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------| | ODS FHIR R4 API | Source code for the API proxy, and specification. | [GitHub repo](https://github.com/NHSDigital/organisation-data-terminology-api) | | FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) | ## Environments and testing | Environments | Base URLs | | ----------------- | ---------------------------------------------------------------------- | | Sandbox | https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir | | Integration (INT) | https://int.api.service.nhs.uk/organisation-data-terminology-api/fhir | | Production | https://api.service.nhs.uk/organisation-data-terminology-api/fhir | For example: `https://api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization/RJY` returns the dataset for the organisation whose ODS code is RJY. All 3 environments are updated daily (scheduled for 2am) with the full scope of organisation reference data. ### Integration testing You can use the integration environment to perform your integration testing. ## Onboarding You need to confirm your eligibility with us before you can go live with this API. We call this onboarding. As part of this process, you need to answer a simple set of questions, detailing information about yourself and your organisation. We will then reach out to request information to enable your software application before we approve your request. To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding).

To get started, sign in or create a developer account, then select 'product onboarding'.

## Contact us For help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support). servers: - url: https://sandbox.api.service.nhs.uk/organisation-data-terminology-api/fhir description: Sandbox 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. Refer to our [Implementation Guidance](https://simplifier.net/guide/organisation-data-services/Home/FHIR-Assets/Profiles#UKCore-Organization) pages for profiles and other FHIR assets. 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. Alternatively, you can try out the sandbox using our Postman collection: [![Run in Postman](https://run.pstmn.io/button.svg)](https://documenter.getpostman.com/view/26163840/2sA3dvmD94) 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. For further information about the application of lastChangeDate and how it should be queried, please refer to the [ODS Reference Data Catalogue page for LastChangeDate](https://www.odsdatasearchandexport.nhs.uk/referenceDataCatalogue/LastChangeDate_636505291.html). 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 `ODSOrganisationRole` 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 `ODSOrganisationRole` 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. any search which generates a response larger than 5mb will generate an error. We recommend you use a an appropriate limit and use _offset to page through the data, until you have collected all results By default the first 20 records will be returned 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://int.api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?_count=2&lastChangeDate=lt2023-05-04&lastChangeDate=gt2023-05-02 - relation: next url: >- https://int.api.service.nhs.uk/organisation-data-terminology-api/fhir/Organization?_count=2&_offset=2&lastChangeDate=lt2023-05-04&lastChangeDate=gt2023-05-02 entry: - fullUrl: >- https://int.api.service.nhs.uk/organisation-data-terminology-api/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://int.api.service.nhs.uk/organisation-data-terminology-api/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. A FHIR OrganizationAffiliation Resource will be returned when a valid id is provided. Refer to our [Implementation Guidance](https://simplifier.net/guide/organisation-data-services/Home/FHIR-Assets/Profiles#UKCore-OrganizationAffiliation) pages for profiles and other FHIR assets. 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-organization' - known within the ORD products as the Source Organisation * 'participating-organization' - 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. You can try out the sandbox using the 'Try this API' feature on this page. Alternatively, you can try out the sandbox using our Postman collection: [![Run in Postman](https://run.pstmn.io/button.svg)](https://documenter.getpostman.com/view/26163840/2sA3dvmD94) 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-organization 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. any search which generates more than 50,000 results will generate an error. we recomend you use a limit 1000 of and use _offset to page through the data, until you have collected all results By default the first 20 records will be returned 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://int.api.service.nhs.uk/organisation-data-terminology-api/fhir/OrganizationAffiliation?primary-organization=FDC49 entry: - fullUrl: >- https://int.api.service.nhs.uk/organisation-data-terminology-api/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://int.api.service.nhs.uk/organisation-data-terminology-api/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://int.api.service.nhs.uk/organisation-data-terminology-api/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. Refer to our [Implementation Guidance](https://simplifier.net/guide/organisation-data-services/Home/FHIR-Assets/Profiles#UKCore-Organization) pages for profiles and other FHIR assets. ## 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 2011 Lower Super Output Area (LSOA11) 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. Refer to our [Implementation Guidance](https://simplifier.net/guide/organisation-data-services/Home/FHIR-Assets/Profiles#UKCore-OrganizationAffiliation) pages for profiles and other FHIR assets. 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 possible that we create or receive organisations which are created in error and removed from the source data. When this occurs there is no update to the record, it is simply no longer available. To inform you 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 remove 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 its 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 You can return a summary of each codeSystem 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. When you perform a search, unless you specify otherwise, we will provide a result in 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 can be returned 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` For example: `/CodeSystem?system=https://digital.nhs.uk/services/organisation-data-service/CodeSystem/succession` ## 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 RE10 (nominated payee for) * presence of successor or predecessor information * indicator for onward succession * geographic values such as Local Authority boundary, Integrated Care Board boundary or 2011 Lower Super Output Area (LSOA11) ### organisation-relationship-instance https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-relationship-instance - Contains relationship history ### organisation-role-instance https://digital.nhs.uk/services/organisation-data-service/CodeSystem/organization-role-instance - Contains role history ### Succession https://digital.nhs.uk/services/organisation-data-service/CodeSystem/succession - Contains succession (merger and acquisition) data for statutory organisations ## 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 practitioners 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 Issuing authority, start and end dates for the identifier are included. ## Geographic Data ### geography-name 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. ### postcode 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: | Attribute name | Description | |---------------------------------|--------------------------------------------------------| | `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 ### ODSOrganisationRole 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 you can return all roles or individual role codes can be returned or validated. Our [Reference Data Catalogue](https://odsdatasearchandexport.dc4h.link/referenceDataCatalogue/index.html) contains more help information. This CodeSystem has 1 additional Property: `primaryRole` which contains a true/false value if the role is a primary role or not. ### ODSRelationship 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`. ### practitioner-role 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. For example: `/ValueSet/$expand` in the example request body below we filter on lastChangeDate and limit the response to 2 records with `count`. searches which generate more than 50,000 results will generate an error, so we recommend that you use count and offset together to ensure you have collected all the required results. 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. 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 Helpdesk Exeter telecom: - system: email value: exeter.helpdesk@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