Skip to main content

Search parameters

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:

{"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=2018-01-12

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.

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.

Postcode

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

LastChangeDate

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=2019-10-06

This query will return all organisations created or updated on or after 6 October 2019. Please also refer to guidance for consumers who have built a dependency on LastChangeDate.

Record status

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.

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
RO218 Commissioning Hub

 

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.

Record class

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 format

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.

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.

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

Offset

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

Last edited: 11 October 2019 3:05 pm