Skip to main content

Organisation Data Service: Guidance for developers

Find developer guidance for the Organisation Data Service (ODS), including information on the ODS API Suite and ORD XML supporting products.


September 2019

From 1 April 2020 onwards new organisation codes will conform to a single uniform structure of five alternating alphabetic and numeric characters with a format of ANANA. Please refer to detailed guidance on this change at our information portal. In order to support users who are consuming the data via the ODS API Suite a specific instance will be hosted for a limited period to allow test and assurance activities to take place. The content is based on the August 2019 XML data release. Consumers wishing to carry out testing should use and provide feedback via marking your query for the attention of the ODS team.

Download a spreadsheet containing the ANANA codes which appear in the UAT instance. 

August 2019

The ODS ORD Search endpoint has been enhanced to support membership queries. Find out more about the Search endpoint.


Hosting Organisation Reference Data via an API is a step increase in service for all ORD consumers.  Consumers are able to access the data at their convenience rather than being tied in to fixed release schedules.  The data hosted within the service is updated daily directly from the ODS team and is available to all users and is accessible to any browser or REST client via the internet.  Users can baseline using XML products and read updates direct from the ORD API or use the service for Ad hoc queries using the search facility documented within these pages.

The API can be called using a REST client such as Postman or by building a custom REST client.

Please note that the IP address for the API is dynamic and it is advised that firewalls are configured using the FQDN (Fully Qualified Domain Name) of the service –

This guide details the ODS ORD API, which is designed to be compatible with the Organisation Reference Data information standard (DCB0090). This API contains the full record from ODS.

Note that the ORD API returns data in JSON format by default. Users requiring XML need to append the HTTP parameter “_format=xml” to retrieve data formatted as XML.

Developer resources

ODS ORD API endpoints

Find information about organisation, search, sync and CodeSystems endpoints.

ODS ORD API synchroniser demonstrator

Find out about the ODS ORD API synchroniser demonstrator.

HTTP headers

Find out about HTTP headers and REST client headers.

Search parameters

Find out about search parameters, including information on Organisation Name, postcodes, LastChangeDate, record status, PrimaryRoleID and NonPrimaryRoleID, record class and summary record format.

LastChangeDate guidance

Guidance for consumers who have built a dependency on LastChangeDate.

ORD how to guides

ORD impact summary

This is a summary of ORD impact however, ORD users should explore their own systems and processes to identify specific imapacts to their own organisations.

ORD tools diagram

This can be used as a guide to the ORD tools available to you.

ORD scope definition

This document shows organisation types which will transition to ANANA code formats, and csv files which will be deprecated as the content is available via ORD (in XML or JSON format via the ORD API).

Creating a baseline

Find out about creating a baseline, including information on full files, archive files and usage.

How to convert XML to CSV

The change to XML introduces a different way of working for ODS data users. A range of tools have been developed to assist users. This guide explains how to transform transforming the XML content to meet local needs.

How to extract specific organisation types from the XML file

The change to XML introduces a different way of working for ODS data users. A range of tools have been developed to assist users. The primary constrain tool focusses on extracting specific organisation types from the XML file.

How to get TRUD access and automate downloads

The XML Organisation Reference Data product is available via the Terminology Reference Update Distribution (TRUD) service. This guide explains how to access the product and automate downloads.

How to identify which amended records have been updated

Find out about identifying which amended records have been updated in the legacy CSV files and XML files.

How to map ODS csv files to XML roles

The old ODS approach uses a large number of separate CSV files, with their content being constrained by organisation type. The new approach sees all types of organisation published within a single XML file, with new ‘role’ meta-data values to identify organisation type.

How to obtain organisation data via the ODS API suite

An Application Programming Interface (API) for organisation data has been developed to give data users direct access to health and social care organisation reference data. Find out how to get this data via the ODS API suite.

How to obtain XML data - release mechanisms and frequency

The primary release vehicle for health and social care organisation reference data is a single file in eXtensible Markup Language (XML) format. The XML file is published monthly along with several supporting products. The same data is also made available through an Application Programme Interface (API).

How to understand organisation succession

Organisation succession is where one or more new or existing entities displace or merge with one or more records which have closed.

How to understand relationship meta data – how it works, names and definitions

Find out how to understand relationship meta data, including how it works, along with information about names and definitions.

How to derive NHS hierarchy from ORD

In order to derive NHS hierarchy information (High Level Health Authority and National Grouping) from ORD, the relationship meta data must be used. There are various ‘named relationships’ in ORD which describe how one organisation entity is linked to another.

How to use role meta data to identify the type of organisation

The change to XML introduces a different way of working for many ODS data users. To determine a type of organisation within XML, role meta data must be used. Role meta data describes what an organisation does, such as the overall function(s) it serves. Find out more about meta data in this guide.

Glossary and links

A glossary specific to the Health & Social Care Organisation Reference Data (HSCOrgRefData) XML schema can be found within Appendix 1 of the data item catalogue.

All supporting products relating to XML Organisation Data (including the XML Schema, Interactive Object Model and Technical Specification) can be found within these ODS pages.

For technical queries regarding the ODS API Suite, or general queries regarding ODS data, please contact

Last edited: 25 February 2021 11:34 am