Search parameters

When using the search endpoint (https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?) summary information is returned for each match as follows:

{"Organisations": [
{
"Name": "116 ST GREGORY'S CRESCENT",
"OrgId": "G82032001",
"Status": "Active",
"OrgRecordClass": "RC2",
"PostCode": "DA12 4JW",
"LastChangeDate": "2018-04-18",
"PrimaryRoleId": "RO96",
"PrimaryRoleDescription": "BRANCH SURGERY",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/G82032001"
} ]
}

All search parameters listed on this page can be combined to filter for records, such as:

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?OrgRecordClass=RC2&LastChangeDate=2020-09-12

The above search returns summary information for one or more organisations where the OrgRecordClass and LastChangeDate match.

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.

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Name=medical&_format=xml

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:

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?PostCode=LS1

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:

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?PostCode=LS14BT

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.

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?LastChangeDate=2020-10-06

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).

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Status=InActive

This will return summary information for all organisation records with a status of Inactive.

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.
 

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.

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?PrimaryRoleId=RO101

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').

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?NonPrimaryRoleId=RO76

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.

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Roles=RO197,RO107

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:

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Roles=

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

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?OrgRecordClass=RC1

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.

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/X09?_format=xml

The above search returns data as xml for a single organisation.

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Name=Connecting&_format=xml

The above search returns summary information for one or more organisations with the summary formatted as xml.

Results are limited to 20 records by default.  This can be extended to a maximum of 1,000 using the Limit parameter.

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Name=Trust&Limit=100

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. 

https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Name=Trust&Offset=20