Skip to main content

Search parameters

Find out about search parameters, including information on postcodes, record status, PrimaryRoleID and NonPrimaryRoleID and record class.

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.

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

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. Primary Roles are listed within the OrgRefData Data Item Catalogue which is available on the ODS XML supporting products page, within the 'ancilliary' zip file. Organisations may also have one or more non primary roles if they carry out additional functions. Non Primary Roles are also listed within the Data Item Catalogue. Each Role has a Role ID and a Role Name, for example:

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.

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.

Default number of records returned (limit)

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 about 'Offset'.

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

Last edited: 9 July 2019 12:10 pm