Organisation Data Service (ODS) Implementation Guide

WARNING

This guidance is under active development by NHS England and content may be added or updated on a regular basis.

This site is provided for information only and it is advised not to develop against these specifications until a formal announcement has been made.

For more information, see the ODS Roadmap

Capability Statement

The Capability Statement documents the required capabilities (behaviours) of a FHIR Server or Client Application.

The ODS-FHIR-API Capability Statement documents required capabilities for the FHIR Server serving the ODS as part of NHS Spine.

HTML View

REST Capabilities Server

Mode

Server

Security

Cors	False
Service	OAuth
Description	This API is application-restricted, meaning we authenticate the calling application but not the end user. We are using OAuth 2.0. To use this access mode, you will be provided with a client id and client secret. These are currently set to expire after 24 hours, after which time you will need to request a new token. A client credentials token is necessary to obtain to authenticate with the Terminology Server. A free tool like Postman can be used to obtain tokens and issue requests, or any other RESTful client

Resource Interactions

Resource Type	Profile	Supported Profiles	Read	SearchType
Organization	UK Core Organization		✓	✓
OrganizationAffiliation	https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation		✓	✓

Search Parameters per resource type

Organization

Name	Type	Level
identifier	token	Supported
active	token	Supported
type	token	Supported
name	string	Supported
address-country	string	Supported
roleCode	token	Supported
lastChangeDate	date	Supported
activeRoleCode	token	Supported

OrganizationAffiliation

Name	Type	Level
identifier	token	Supported
active	token	Supported
primary-organization	reference	Supported
participating-organization	reference	Supported

Tree View

CapabilityStatement

id : England-ODS-Requirements

url : https://fhir.nhs.uk/England/CapabilityStatement/England-ODS-Requirements

version : 0.0.2

name : EnglandODSRequirements

title : England ODS Requirements

status : draft

date : 2024-02-14

publisher : NHS England

contact

name : NHS England

telecom

system : email

value : interoperabilityteam@nhs.net

use : work

rank : 1

description : Requirements for NHS England ODS FHIR API Implementation Guide

jurisdiction

coding

system : urn:iso:std:iso:3166:-2

code : GB-ENG

display : England

purpose : Requirements for NHS England ODS FHIR API Implementation Guide, to specify the RESTFul interactions, supported profiles, and expected minimum SearchParamneters.

copyright : Copyright © 2023+ NHS England Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html.

kind : requirements

fhirVersion : 4.0.1

format : application/fhir+json

format : application/fhir+xml

implementationGuide : https://simplifier.net/guide/organisational-data-services

rest

mode : server

security

cors : False

service

coding

system : http://terminology.hl7.org/CodeSystem/restful-security-service

code : OAuth

description : This API is application-restricted, meaning we authenticate the calling application but not the end user. We are using OAuth 2.0. To use this access mode, you will be provided with a client id and client secret. These are currently set to expire after 24 hours, after which time you will need to request a new token. A client credentials token is necessary to obtain to authenticate with the Terminology Server. A free tool like Postman can be used to obtain tokens and issue requests, or any other RESTful client

resource

type : Organization

profile : https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization

interaction

code : read

interaction

code : search-type

searchParam

name : identifier

definition : http://hl7.org/fhir/SearchParameter/identifier

type : token

searchParam

name : active

definition : http://hl7.org/fhir/SearchParameter/active

type : token

searchParam

name : type

definition : http://hl7.org/fhir/SearchParameter/type

type : token

searchParam

name : name

definition : http://hl7.org/fhir/SearchParameter/name

type : string

searchParam

name : address-country

definition : http://hl7.org/fhir/SearchParameter/address-country

type : string

searchParam

name : roleCode

definition : https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-RoleCode

type : token

searchParam

name : lastChangeDate

definition : https://fhir.nhs.uk/England/SearchParameter/England-Extension-TypedDateTime-LastChangeDate

type : date

searchParam

name : activeRoleCode

definition : https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-ActiveRoleCode

type : token

resource

type : OrganizationAffiliation

profile : https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation

interaction

code : read

interaction

code : search-type

searchParam

name : identifier

definition : http://hl7.org/fhir/SearchParameter/identifier

type : token

searchParam

name : active

definition : http://hl7.org/fhir/SearchParameter/active

type : token

searchParam

name : primary-organization

definition : http://hl7.org/fhir/SearchParameter/primary-organization

type : reference

searchParam

name : participating-organization

definition : http://hl7.org/fhir/SearchParameter/participating-organization

type : reference

Table View

CapabilityStatement.id[0]	England-ODS-Requirements
CapabilityStatement.url[0]	https://fhir.nhs.uk/England/CapabilityStatement/England-ODS-Requirements
CapabilityStatement.version[0]	0.0.2
CapabilityStatement.name[0]	EnglandODSRequirements
CapabilityStatement.title[0]	England ODS Requirements
CapabilityStatement.status[0]	draft
CapabilityStatement.date[0]	2024-02-14
CapabilityStatement.publisher[0]	NHS England
CapabilityStatement.contact[0].name[0]	NHS England
CapabilityStatement.contact[0].telecom[0].system[0]	email
CapabilityStatement.contact[0].telecom[0].value[0]	interoperabilityteam@nhs.net
CapabilityStatement.contact[0].telecom[0].use[0]	work
CapabilityStatement.contact[0].telecom[0].rank[0]	1
CapabilityStatement.description[0]	Requirements for NHS England ODS FHIR API Implementation Guide
CapabilityStatement.jurisdiction[0].coding[0].system[0]	urn:iso:std:iso:3166:-2
CapabilityStatement.jurisdiction[0].coding[0].code[0]	GB-ENG
CapabilityStatement.jurisdiction[0].coding[0].display[0]	England
CapabilityStatement.purpose[0]	Requirements for NHS England ODS FHIR API Implementation Guide, to specify the RESTFul interactions, supported profiles, and expected minimum SearchParamneters.
CapabilityStatement.copyright[0]	Copyright © 2023+ NHS England Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at https://www.hl7.org/fhir/license.html.
CapabilityStatement.kind[0]	requirements
CapabilityStatement.fhirVersion[0]	4.0.1
CapabilityStatement.format[0]	application/fhir+json
CapabilityStatement.format[1]	application/fhir+xml
CapabilityStatement.implementationGuide[0]	https://simplifier.net/guide/organisational-data-services
CapabilityStatement.rest[0].mode[0]	server
CapabilityStatement.rest[0].security[0].cors[0]	False
CapabilityStatement.rest[0].security[0].service[0].coding[0].system[0]	http://terminology.hl7.org/CodeSystem/restful-security-service
CapabilityStatement.rest[0].security[0].service[0].coding[0].code[0]	OAuth
CapabilityStatement.rest[0].security[0].description[0]	This API is application-restricted, meaning we authenticate the calling application but not the end user. We are using OAuth 2.0. To use this access mode, you will be provided with a client id and client secret. These are currently set to expire after 24 hours, after which time you will need to request a new token. A client credentials token is necessary to obtain to authenticate with the Terminology Server. A free tool like Postman can be used to obtain tokens and issue requests, or any other RESTful client
CapabilityStatement.rest[0].resource[0].type[0]	Organization
CapabilityStatement.rest[0].resource[0].profile[0]	https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization
CapabilityStatement.rest[0].resource[0].interaction[0].code[0]	read
CapabilityStatement.rest[0].resource[0].interaction[1].code[0]	search-type
CapabilityStatement.rest[0].resource[0].searchParam[0].name[0]	identifier
CapabilityStatement.rest[0].resource[0].searchParam[0].definition[0]	http://hl7.org/fhir/SearchParameter/identifier
CapabilityStatement.rest[0].resource[0].searchParam[0].type[0]	token
CapabilityStatement.rest[0].resource[0].searchParam[1].name[0]	active
CapabilityStatement.rest[0].resource[0].searchParam[1].definition[0]	http://hl7.org/fhir/SearchParameter/active
CapabilityStatement.rest[0].resource[0].searchParam[1].type[0]	token
CapabilityStatement.rest[0].resource[0].searchParam[2].name[0]	type
CapabilityStatement.rest[0].resource[0].searchParam[2].definition[0]	http://hl7.org/fhir/SearchParameter/type
CapabilityStatement.rest[0].resource[0].searchParam[2].type[0]	token
CapabilityStatement.rest[0].resource[0].searchParam[3].name[0]	name
CapabilityStatement.rest[0].resource[0].searchParam[3].definition[0]	http://hl7.org/fhir/SearchParameter/name
CapabilityStatement.rest[0].resource[0].searchParam[3].type[0]	string
CapabilityStatement.rest[0].resource[0].searchParam[4].name[0]	address-country
CapabilityStatement.rest[0].resource[0].searchParam[4].definition[0]	http://hl7.org/fhir/SearchParameter/address-country
CapabilityStatement.rest[0].resource[0].searchParam[4].type[0]	string
CapabilityStatement.rest[0].resource[0].searchParam[5].name[0]	roleCode
CapabilityStatement.rest[0].resource[0].searchParam[5].definition[0]	https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-RoleCode
CapabilityStatement.rest[0].resource[0].searchParam[5].type[0]	token
CapabilityStatement.rest[0].resource[0].searchParam[6].name[0]	lastChangeDate
CapabilityStatement.rest[0].resource[0].searchParam[6].definition[0]	https://fhir.nhs.uk/England/SearchParameter/England-Extension-TypedDateTime-LastChangeDate
CapabilityStatement.rest[0].resource[0].searchParam[6].type[0]	date
CapabilityStatement.rest[0].resource[0].searchParam[7].name[0]	activeRoleCode
CapabilityStatement.rest[0].resource[0].searchParam[7].definition[0]	https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-ActiveRoleCode
CapabilityStatement.rest[0].resource[0].searchParam[7].type[0]	token
CapabilityStatement.rest[0].resource[1].type[0]	OrganizationAffiliation
CapabilityStatement.rest[0].resource[1].profile[0]	https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation
CapabilityStatement.rest[0].resource[1].interaction[0].code[0]	read
CapabilityStatement.rest[0].resource[1].interaction[1].code[0]	search-type
CapabilityStatement.rest[0].resource[1].searchParam[0].name[0]	identifier
CapabilityStatement.rest[0].resource[1].searchParam[0].definition[0]	http://hl7.org/fhir/SearchParameter/identifier
CapabilityStatement.rest[0].resource[1].searchParam[0].type[0]	token
CapabilityStatement.rest[0].resource[1].searchParam[1].name[0]	active
CapabilityStatement.rest[0].resource[1].searchParam[1].definition[0]	http://hl7.org/fhir/SearchParameter/active
CapabilityStatement.rest[0].resource[1].searchParam[1].type[0]	token
CapabilityStatement.rest[0].resource[1].searchParam[2].name[0]	primary-organization
CapabilityStatement.rest[0].resource[1].searchParam[2].definition[0]	http://hl7.org/fhir/SearchParameter/primary-organization
CapabilityStatement.rest[0].resource[1].searchParam[2].type[0]	reference
CapabilityStatement.rest[0].resource[1].searchParam[3].name[0]	participating-organization
CapabilityStatement.rest[0].resource[1].searchParam[3].definition[0]	http://hl7.org/fhir/SearchParameter/participating-organization
CapabilityStatement.rest[0].resource[1].searchParam[3].type[0]	reference

XML View

<CapabilityStatement xmlns="http://hl7.org/fhir">
    <id value="England-ODS-Requirements" />
    <url value="https://fhir.nhs.uk/England/CapabilityStatement/England-ODS-Requirements" />
    <version value="0.0.2" />
    <name value="EnglandODSRequirements" />
    <title value="England ODS Requirements" />
    <status value="draft" />
    <date value="2024-02-14" />
    <publisher value="NHS England" />
    <contact>
        <name value="NHS England" />
        <telecom>
            <system value="email" />
            <value value="interoperabilityteam@nhs.net" />
            <use value="work" />
            <rank value="1" />
        </telecom>
    </contact>
    <description value="Requirements for NHS England ODS FHIR API Implementation Guide" />
    <jurisdiction>
        <coding>
            <system value="urn:iso:std:iso:3166:-2" />
            <code value="GB-ENG" />
            <display value="England" />
        </coding>
    </jurisdiction>
    <purpose value="Requirements for NHS England ODS FHIR API Implementation Guide, to specify the RESTFul interactions, supported profiles, and expected minimum SearchParamneters." />
    <copyright value="Copyright &#169; 2023+ NHS England Licensed under the Apache License, Version 2.0 (the &amp;quot;License&amp;quot;); you may not use this file except in compliance with the License. You may obtain a copy of the License at  http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &amp;quot;AS IS&amp;quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7&#174; FHIR&#174; standard Copyright &#169; 2011+ HL7 The HL7&#174; FHIR&#174; standard is used under the FHIR license. You may obtain a copy of the FHIR license at  https://www.hl7.org/fhir/license.html." />
    <kind value="requirements" />
    <fhirVersion value="4.0.1" />
    <format value="application/fhir+json" />
    <format value="application/fhir+xml" />
    <implementationGuide value="https://simplifier.net/guide/organisational-data-services" />
    <rest>
        <mode value="server" />
        <security>
            <cors value="false" />
            <service>
                <coding>
                    <system value="http://terminology.hl7.org/CodeSystem/restful-security-service" />
                    <code value="OAuth" />
                </coding>
            </service>
            <description value="This API is application-restricted, meaning we authenticate the calling application but not the end user.  We are using OAuth 2.0. To use this access mode, you will be provided with a client id and client secret.  These are currently set to expire after 24 hours, after which time you will need to request a new token.  A client credentials token is necessary to obtain to authenticate with the Terminology Server. A free tool like Postman can be used to obtain tokens and issue requests, or any other RESTful client" />
        </security>
        <resource>
            <type value="Organization" />
            <profile value="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization" />
            <interaction>
                <code value="read" />
            </interaction>
            <interaction>
                <code value="search-type" />
            </interaction>
            <searchParam>
                <name value="identifier" />
                <definition value="http://hl7.org/fhir/SearchParameter/identifier" />
                <type value="token" />
            </searchParam>
            <searchParam>
                <name value="active" />
                <definition value="http://hl7.org/fhir/SearchParameter/active" />
                <type value="token" />
            </searchParam>
            <searchParam>
                <name value="type" />
                <definition value="http://hl7.org/fhir/SearchParameter/type" />
                <type value="token" />
            </searchParam>
            <searchParam>
                <name value="name" />
                <definition value="http://hl7.org/fhir/SearchParameter/name" />
                <type value="string" />
            </searchParam>
            <searchParam>
                <name value="address-country" />
                <definition value="http://hl7.org/fhir/SearchParameter/address-country" />
                <type value="string" />
            </searchParam>
            <searchParam>
                <name value="roleCode" />
                <definition value="https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-RoleCode" />
                <type value="token" />
            </searchParam>
            <searchParam>
                <name value="lastChangeDate" />
                <definition value="https://fhir.nhs.uk/England/SearchParameter/England-Extension-TypedDateTime-LastChangeDate" />
                <type value="date" />
            </searchParam>
            <searchParam>
                <name value="activeRoleCode" />
                <definition value="https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-ActiveRoleCode" />
                <type value="token" />
            </searchParam>
        </resource>
        <resource>
            <type value="OrganizationAffiliation" />
            <profile value="https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation" />
            <interaction>
                <code value="read" />
            </interaction>
            <interaction>
                <code value="search-type" />
            </interaction>
            <searchParam>
                <name value="identifier" />
                <definition value="http://hl7.org/fhir/SearchParameter/identifier" />
                <type value="token" />
            </searchParam>
            <searchParam>
                <name value="active" />
                <definition value="http://hl7.org/fhir/SearchParameter/active" />
                <type value="token" />
            </searchParam>
            <searchParam>
                <name value="primary-organization" />
                <definition value="http://hl7.org/fhir/SearchParameter/primary-organization" />
                <type value="reference" />
            </searchParam>
            <searchParam>
                <name value="participating-organization" />
                <definition value="http://hl7.org/fhir/SearchParameter/participating-organization" />
                <type value="reference" />
            </searchParam>
        </resource>
    </rest>
</CapabilityStatement>

JSON View

{
    "resourceType": "CapabilityStatement",
    "id": "England-ODS-Requirements",
    "url": "https://fhir.nhs.uk/England/CapabilityStatement/England-ODS-Requirements",
    "version": "0.0.2",
    "name": "EnglandODSRequirements",
    "title": "England ODS Requirements",
    "status": "draft",
    "date": "2024-02-14",
    "publisher": "NHS England",
    "contact":  [
        {
            "name": "NHS England",
            "telecom":  [
                {
                    "system": "email",
                    "value": "interoperabilityteam@nhs.net",
                    "use": "work",
                    "rank": 1
                }
            ]
        }
    ],
    "description": "Requirements for NHS England ODS FHIR API Implementation Guide",
    "jurisdiction":  [
        {
            "coding":  [
                {
                    "system": "urn:iso:std:iso:3166:-2",
                    "code": "GB-ENG",
                    "display": "England"
                }
            ]
        }
    ],
    "purpose": "Requirements for NHS England ODS FHIR API Implementation Guide, to specify the RESTFul interactions, supported profiles, and expected minimum SearchParamneters.",
    "copyright": "Copyright © 2023+ NHS England Licensed under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License. You may obtain a copy of the License at  http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. HL7® FHIR® standard Copyright © 2011+ HL7 The HL7® FHIR® standard is used under the FHIR license. You may obtain a copy of the FHIR license at  https://www.hl7.org/fhir/license.html.",
    "kind": "requirements",
    "fhirVersion": "4.0.1",
    "format":  [
        "application/fhir+json",
        "application/fhir+xml"
    ],
    "implementationGuide":  [
        "https://simplifier.net/guide/organisational-data-services"
    ],
    "rest":  [
        {
            "mode": "server",
            "security": {
                "cors": false,
                "service":  [
                    {
                        "coding":  [
                            {
                                "system": "http://terminology.hl7.org/CodeSystem/restful-security-service",
                                "code": "OAuth"
                            }
                        ]
                    }
                ],
                "description": "This API is application-restricted, meaning we authenticate the calling application but not the end user.  We are using OAuth 2.0. To use this access mode, you will be provided with a client id and client secret.  These are currently set to expire after 24 hours, after which time you will need to request a new token.  A client credentials token is necessary to obtain to authenticate with the Terminology Server. A free tool like Postman can be used to obtain tokens and issue requests, or any other RESTful client"
            },
            "resource":  [
                {
                    "type": "Organization",
                    "profile": "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization",
                    "interaction":  [
                        {
                            "code": "read"
                        },
                        {
                            "code": "search-type"
                        }
                    ],
                    "searchParam":  [
                        {
                            "name": "identifier",
                            "definition": "http://hl7.org/fhir/SearchParameter/identifier",
                            "type": "token"
                        },
                        {
                            "name": "active",
                            "definition": "http://hl7.org/fhir/SearchParameter/active",
                            "type": "token"
                        },
                        {
                            "name": "type",
                            "definition": "http://hl7.org/fhir/SearchParameter/type",
                            "type": "token"
                        },
                        {
                            "name": "name",
                            "definition": "http://hl7.org/fhir/SearchParameter/name",
                            "type": "string"
                        },
                        {
                            "name": "address-country",
                            "definition": "http://hl7.org/fhir/SearchParameter/address-country",
                            "type": "string"
                        },
                        {
                            "name": "roleCode",
                            "definition": "https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-RoleCode",
                            "type": "token"
                        },
                        {
                            "name": "lastChangeDate",
                            "definition": "https://fhir.nhs.uk/England/SearchParameter/England-Extension-TypedDateTime-LastChangeDate",
                            "type": "date"
                        },
                        {
                            "name": "activeRoleCode",
                            "definition": "https://fhir.nhs.uk/England/SearchParameter/England-Extension-OrganisationRole-ActiveRoleCode",
                            "type": "token"
                        }
                    ]
                },
                {
                    "type": "OrganizationAffiliation",
                    "profile": "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OrganizationAffiliation",
                    "interaction":  [
                        {
                            "code": "read"
                        },
                        {
                            "code": "search-type"
                        }
                    ],
                    "searchParam":  [
                        {
                            "name": "identifier",
                            "definition": "http://hl7.org/fhir/SearchParameter/identifier",
                            "type": "token"
                        },
                        {
                            "name": "active",
                            "definition": "http://hl7.org/fhir/SearchParameter/active",
                            "type": "token"
                        },
                        {
                            "name": "primary-organization",
                            "definition": "http://hl7.org/fhir/SearchParameter/primary-organization",
                            "type": "reference"
                        },
                        {
                            "name": "participating-organization",
                            "definition": "http://hl7.org/fhir/SearchParameter/participating-organization",
                            "type": "reference"
                        }
                    ]
                }
            ]
        }
    ]
}

Examples

None provided at this time.

WARNING

Capability Statement

HTML View

REST Capabilities Server

Security

Resource Interactions

Search Parameters per resource type

Tree View

Table View

XML View

JSON View

Examples

Propose a change to England-ODS-Requirements