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.
Search endpoint
Find out about the search endpoint, including a description, parameters, the summary record format and examples.
Page contents
Endpoint
https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?{search parameters}
Description
Search the ODS database based on several parameters and return a summary of multiple organisations. The parameters can be used independently or as part of a search combination to help with reducing the number of search results returned. The below outlines the search parameter syntax used with some basic examples provided.
Parameters
| Parameter | Description |
_format |
String - case sensitive Can take xml, json, text/json, text/xml, application/json and application/xml as arguments. If this parameter is not supplied, the format will default to JSON. Note that _format specifies the format in which summary information is displayed and also the links to individual records. If _format=xml is specified in the search term then the OrgLink entries will have the argument ?_format=xml appended to link the individual records. |
Name |
string - not case sensitive Search for organisations based on name. Organisations that contain the argument string in their name are returned. |
PostCode |
string - not case sensitive Search for organisations based on postcode. Organisations that contain the argument string in their postcode are returned. |
LastChangeDate |
Date Search for organisations based on their last changed date. Date must be in format YYYY-MM-DD. The search is greater than or equal to. Dates are restricted to 185 days from present. Please also refer to guidance for consumers who have built a dependency on LastChangeDate. |
Status |
string - not case sensitive Search for organisations based on their active status. Arguments can be Active or Inactive. |
PrimaryRoleId |
string - not case sensitive Search for organisations based on their primary role codes. A single role code must be passed through as an argument. The Roles endpoint allows consumers to query the Code Systems meta data relating to roles – read our guidance on the Roles endpoint. |
NonPrimaryRoleId |
string - not case sensitive Search for organisations based on their non primary role codes. A single role code must be passed through as an argument. The Roles endpoint allows consumers to query the Code Systems meta data relating to roles – see guidance on the Roles endpoint. |
Roles |
String – not case sensitive. Search for organisations based on their primary or non primary role codes. Multiple role codes can be passed through as an argument, separated by a comma. The Roles endpoint allows consumers to query the Code Systems meta data relating to roles – see guidance on the Roles endpoint. |
OrgRecordClass |
string - not case sensitive Search for organisations based on their record class. |
Limit |
integer Used to limit the number of organisations returned by response. The argument can range from 1 to 1,000. |
Offset |
integer |
Relationship search
The relationship search function allows consumers to retrieve records related to a given organisation, or all relationships of a given type. Within the ODS data, relationships exist between source records and target organisations. The relationships are uni-directional and are held within the record on the source organisation, such as where a source record is a Trust site its target would generally be a Trust, and the relationship would be represented as RE6 (IS OPERATED BY). The relationship search allows all source records related to the Trust be returned.
The relationship search takes the following parameters:
RelTypeId |
List of 1 or more Relationship Type IDs (required) The Relationships endpoint allows consumers to query the Code Systems meta data relating to Relationship Types – see guidance on the Relationships endpoint. Information regarding the Relationship Types which can exist between source and target Primary Roles is available in the XMLRelationshipRules spreadsheet within the XML support products section of the XML Organisations Data Products page. |
TargetOrgId |
String (optional). This is the Target organisation to which the required records are related, e.g. passing in the ODS code for a CCG code would return all Prescribing Cost Centres. |
RelStatus |
String (optional). RelStatus allows returned records to be filtered based on whether the relationship between the Source organisations and the Target Organisation are Active (i.e. the end date of the relationship is not present in the source record). Allowed values are: ALL – returns every relationship, active and inactive. active – returns the Source records where the relationship to the Target Organisation is active. inactive - returns the Source records where the relationship to the Target Organisation is inactive. If the RelStatus parameter is omitted it is interpreted as active. |
LastChangeDate |
Date (optional) Search for related organisations based on their last changed date. The LastChangeDate will relate to when the source record was last updated. This update may not necessarily relate to the relationships in question. Date must be in format YYYY-MM-DD. The search is greater than or equal to. Dates are restricted to 185 days from present. Please also refer to guidance for consumers who have built a dependency on LastChangeDate. |
The parameters above can be passed to the search in any order; however the logic will be applied as:
return any records which have a relationship of a given type (or types) to this Target organisation [with a RelStatus of….].
The Limit, _format and Offset parameters can also be combined within the Membership Search Query.
Example - Target Org specified (Membership search)
To retrieve a subset of source records (using Limit and Offset) which have active relationships to a Target organisation (the CCG 99A in this case) use the following query:
All records returned align to the existing Summary Format, described further down on this page.
Note that the Active Status contained in the Summary Record data should not be confused with the RelStatus passed to the Search itself. It is the Status of any relationship within the scope of the query that is being processed and not the Status of the Source or Target records.
Example – All relationships of a specified type
To retrieve source records which have active relationships of a specified type, where the source organisation record has been amended on or after a specified date (within the last 185 days) use the following query:
Summary Record Format
The following shows the attributes returned in a summary record format:
https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Name=ABES
COPY
{
"Organisations": [
{
"Name": "ABES CROSSGATES DAY & NIGHT LTD",
"OrgId": "P3JX",
"Status": "Active",
"OrgRecordClass": "RC1",
"PostCode": "LS15 8BA",
"LastChangeDate": "2015-02-10",
"PrimaryRoleId": "RO181",
"PrimaryRoleDescription": "PHARMACY HEADQUARTER",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/P3JX"
}
]
}
JSON
Example
The following query returns summary information for one or more organisations where the Name attribute passed in is a substring of the organisation’s name (in this example the organisation name contains ‘Blackdown’.
https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?Name=Blackdown
Find examples on the parameters page.
COPY
{
"Organisations": [
{
"Name": "BLACKDOWN HOSPITAL",
"OrgId": "5HV38",
"Status": "Inactive",
"OrgRecordClass": "RC2",
"PostCode": "DY2 7BX",
"LastChangeDate": "2013-05-08",
"PrimaryRoleId": "RO180",
"PrimaryRoleDescription": "PRIMARY CARE TRUST SITE",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/5HV38"
},
{
"Name": "BLACKDOWN HOSPITAL",
"OrgId": "5PE66",
"Status": "Active",
"OrgRecordClass": "RC2",
"PostCode": "DY2 7BX",
"LastChangeDate": "2013-05-08",
"PrimaryRoleId": "RO180",
"PrimaryRoleDescription": "PRIMARY CARE TRUST SITE",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/5PE66"
},
{
"Name": "BLACKDOWN HOUSE",
"OrgId": "VL8EV",
"Status": "Active",
"OrgRecordClass": "RC1",
"PostCode": "TA9 4HQ",
"LastChangeDate": "2015-09-25",
"PrimaryRoleId": "RO101",
"PrimaryRoleDescription": "CARE HOME SITE",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/VL8EV"
},
{
"Name": "BLACKDOWN NH (TAVISTOCK)",
"OrgId": "8C201",
"Status": "Active",
"OrgRecordClass": "RC1",
"PostCode": "PL19 9QB",
"LastChangeDate": "2018-04-18",
"PrimaryRoleId": "RO157",
"PrimaryRoleDescription": "NON-NHS ORGANISATION",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/8C201"
},
{
"Name": "BLACKDOWN NURSING HOME",
"OrgId": "VLLV9",
"Status": "Active",
"OrgRecordClass": "RC1",
"PostCode": "PL19 9QB",
"LastChangeDate": "2017-02-27",
"PrimaryRoleId": "RO101",
"PrimaryRoleDescription": "CARE HOME SITE",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/VLLV9"
},
{
"Name": "BLACKDOWN PRACTICE",
"OrgId": "L83044",
"Status": "Active",
"OrgRecordClass": "RC1",
"PostCode": "EX15 3SF",
"LastChangeDate": "2016-04-20",
"PrimaryRoleId": "RO177",
"PrimaryRoleDescription": "PRESCRIBING COST CENTRE",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/L83044"
},
{
"Name": "BLACKDOWN PRACTICE",
"OrgId": "NQT0F",
"Status": "Active",
"OrgRecordClass": "RC2",
"PostCode": "EX15 3SF",
"LastChangeDate": "2018-04-18",
"PrimaryRoleId": "RO176",
"PrimaryRoleDescription": "INDEPENDENT SECTOR H/C PROVIDER SITE",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/NQT0F"
},
{
"Name": "BPAS (BLACKDOWN CLINIC)",
"OrgId": "8C980",
"Status": "Inactive",
"OrgRecordClass": "RC1",
"PostCode": "CV32 6RW",
"LastChangeDate": "2013-05-08",
"PrimaryRoleId": "RO157",
"PrimaryRoleDescription": "NON-NHS ORGANISATION",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/8C980"
},
{
"Name": "BPAS BLACKDOWN CLINIC",
"OrgId": "RTHF3",
"Status": "Active",
"OrgRecordClass": "RC2",
"PostCode": "CV32 6RW",
"LastChangeDate": "2013-05-08",
"PrimaryRoleId": "RO198",
"PrimaryRoleDescription": "NHS TRUST SITE",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/RTHF3"
},
{
"Name": "THE BLACKDOWN PRACTICE",
"OrgId": "L83044001",
"Status": "Active",
"OrgRecordClass": "RC2",
"PostCode": "EX14 4JP",
"LastChangeDate": "2018-04-18",
"PrimaryRoleId": "RO96",
"PrimaryRoleDescription": "BRANCH SURGERY",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/L83044001"
}
]
}
JSON
Last edited: 31 December 2020 4:09 pm