We have detected that you are using Internet Explorer to visit this website. Internet Explorer is now being phased out by Microsoft. As a result, NHS Digital no longer supports any version of Internet Explorer for our web-based products, as it involves considerable extra effort and expense, which cannot be justified from public funds. Some features on this site will not work. You should use a modern browser such as Edge, Chrome, Firefox, or Safari. If you have difficulty installing or accessing a different browser, contact your IT support team.
Find out about search parameters, including information on Organisation Name, postcodes, record status, PrimaryRoleID and NonPrimaryRoleID, record class and summary record format.
Summary record format
When using the search endpoint (https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?) summary information is returned for each match as follows:
"Name": "116 ST GREGORY'S CRESCENT",
"PostCode": "DA12 4JW",
"PrimaryRoleDescription": "BRANCH SURGERY",
All search parameters listed on this page can be combined to filter for records, such as:
The above search returns summary information for one or more organisations where the OrgRecordClass and LastChangeDate match.
Name (substring search)
Search for an organisations based on part of its name. Organisations that contain the argument string in their name are returned. Note that the substring value is not case-sensitive.
This will return summary information for all organisations which include the substring “medical” in the name attribute.
Where an organisation address contains a postcode, the ODS ORD API is able to use this to locate an organisation reference data record. There are 2 variations of search available to locate an ODS record using a postcode, neither of which are case sensitive.
Searching using a partial postcode
Where a partial organisation postcode is available e.g. LS1, it is possible to search using this value only:
This will return summary information for one or more organisations which have an exact match to 'LS1' on the first segment of their postcode. The search will not return records for organisations with LS10 or LS13 etc. as the first segment of their postcode.
Searching using an exact match
Where a full postcode for an organisation is known, this can be used to search organisation reference data. To search for an exact postcode the following search should be executed:
This will return summary information for all organisations where the postcode is exactly LS1 4BT. Search expressions are not case sensitive and will return appropriate results with or without a space between the 2 elements of the postcode (i.e. LS14BT and LS1 4BT).
The Search and Sync endpoints support queries for organisations based on their last changed date. The date supplied must be in format YYYY-MM-DD. The search is implemented as greater than or equal to the date provided. Dates are restricted to 185 days from the current day.
This query will return all organisations created or updated on or after 6 October 2020. Please also refer to guidance for consumers who have built a dependency on LastChangeDate.
An organisation record can have a status of Active or Inactive (not case sensitive).
This will return summary information for all organisation records with a status of Inactive.
PrimaryRoleID and NonPrimaryRoleID
All organisations within organisation reference data have a primary role which denotes their core function. Organisations may also have one or more non primary roles if they carry out additional functions. Each Role has a Role ID and a Role Name as shown in the table below.
The roles endpoint allows consumers to query the Code Systems meta data relating to Roles – see guidance on the roles endpoint.
|Primary RoleID||Primary role name|
|RO98||Clinical Commissioning Group|
|RO101||Care Home Site|
|RO177||Prescribing Cost Centre|
|NonPrimary RoleID||Non primary role name|
|RO76||GP Practice Prescribing Cost Centre|
It is the RoleID that must be specified within the API search parameter. When used in a search the role ID is not case sensitive.
The above will return summary information for one or more organisations where the Primary Role ID specified (RO101) is stated within the organisation record (i.e. it will return all records flagged as 'Care Home Sites').
The above will return summary information for one or more organisations where a Non Primary Role ID of RO76 (GP Practice Prescribing Cost Centre) is stated within the organisation record. In this example, GP Practices have a primary role of RO177 Prescribing Cost Centre (along with Out of Hours, Walk in Centres etc), but to filter this down to only include GP Practice settings then a non primary role of RO76 must be specified.
The above API search allows users to query multiple Role IDs in a single search.
A mixture of Primary Role and Non Primary Role IDs can be specified if required.
Note that the argument when searching for multiple roles is:
rather than ?PrimaryRoleId= or ?NonPrimaryRoleId= when searching for one specific role.
The above will return summary information for one or more organisations where a Primary Role ID of RO197 (NHS Trust) or RO107 (Care Trust) is stated within the organisation record. Multiple Role IDs should be separated by a comma and no spaces in the API search.
Health and Social Care Organisation Reference Data currently employs two top-level Record Classes:
- Health and Social Care Organisation (HSCOrg) = RC1
- Health and Social Care Organisation Site (HSCSite) = RC2
The above search returns summary information for one or more organisations where the Record Class matches the string provided, in this example, HSCOrg (RC1). Valid options are RC1 for HSCOrg records and RC2 for HSCSite records. When used in a search the record class codes are not case sensitive.
The Record classes endpoint allows consumers to query the Code Systems meta data relating to Roles – see guidance on the record classes endpoint.
Data is returned as JSON by default however the data can be returned as XML using the _format parameter
Valid options are xml or json (lowercase only). json does not need to be specified.
The above search returns data as xml for a single organisation.
The above search returns summary information for one or more organisations with the summary formatted as xml.
Limit - override the default number of records returned
Results are limited to 20 records by default. This can be extended to a maximum of 1,000 using the Limit parameter.
Used to offset the start point of the result set, by the value specified. The argument can range from 1-<x-total-count>.
Visit the HTTP headers page for further information on combining 'Offset' with 'Limit' to page through queries which return large volumes of records.