Downloads & Data

Download tools and source code; access data sources and services

ODS ORD API Implementation Guide

The information below is draft and covers the functionality included in the current version of the interface.  More detail will be provided as the supporting materials are developed.

The ODS ORD API returns the full dataset approved via SCCI and supports the following endpoints currently.  Note that the interface returns data as JSON by default.

/organisations implements searches for one or more organisations using a number of parameters:

If a search results in no records matching a 404 error is returned.

Single Organisation retrieval

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/X26

  • returns the full data for a single organisation for the Organisation ID specified (X26 in this example)
{"Organisation": {"Date": 
[{"Type": "Operational", "Start": "2013-01-21"}, 
{"Type": "Legal", "Start": "2013-04-01"}], "OrgId": 
{"root": "2.16.840.1.113883.2.1.3.2.4.18.48", 
"assigningAuthorityName": "HSCIC", "extension": "X26"}, 
"orgRecordClass": "RC1", 
"Name": "NHS DIGITAL", 
"Status": "Active", 
"LastChangeDate": "2016-09-09", 
"GeoLoc": 
{"Location": 
{"AddrLn1": "1 TREVELYAN SQUARE", 
"AddrLn2": "BOAR LANE", 
"PostCode": "LS1 6AE", 
"Town": "LEEDS", 
"County": "WEST YORKSHIRE", 
"Country": "ENGLAND"}}, 
"Rels": {"Rel": 
[{"Target": {"PrimaryRoleId": 
{"id": "RO126", "uniqueRoleId": "128996"}, 
"OrgId": {"root": "2.16.840.1.113883.2.1.3.2.4.18.48", 
"assigningAuthorityName": "HSCIC", "extension": "XDH"}}, 
"Status": "Active", 
"id": "RE3", 
"uniqueRelId": 189272, 
"Date": [{"Type": "Operational", "Start": "2013-01-21"}, 
{"Type": "Legal", "Start": "2013-04-01"}]}]}, 
"Roles": {"Role": [{"id": "RO116", "primaryRole": true, 
"uniqueRoleId": 166234, "Status": "Active", 
"Date": [{"Type": "Operational", "Start": "2013-01-21"}, 
{"Type": "Legal", "Start": "2013-04-01"}]}]}, 
"Succs": {"Succ": [{"uniqueSuccId": 36589, "Type": "Predecessor", 
"Target": {"PrimaryRoleId": {"id": "RO189", 
"uniqueRoleId": "136318"}, 
"OrgId": {"root": "2.16.840.1.113883.2.1.3.2.4.18.48", 
"assigningAuthorityName": "HSCIC", "extension": "T1430"}}, 
"Date": [{"Type": "Legal", "Start": "2013-04-01"}]}, 
{"uniqueSuccId": 36688, "Type": "Predecessor", 
"Target": {"PrimaryRoleId": 
{"id": "RO116", "uniqueRoleId": "111933"}, 
"OrgId": {"root": "2.16.840.1.113883.2.1.3.2.4.18.48", 
"assigningAuthorityName": "HSCIC", "extension": "X09"}}, 
"Date": [{"Type": "Legal", "Start": "2013-04-01"}]
}]}}}

 

Multiple Organisation retrieval 

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?Name=Trust

  • returns summary information for one or more organisations where the Name attribute passed in is a substring of the organisation’s name

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?LastChangeDate=2017-10-12

  • returns summary information for one or more organisations where LastChangeDate is greater than or equal to the LastChangeDate on records

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?Status=Active

  • returns summary information for one or more organisations where the organisation record has a status of Active
  • valid options are Active or InActive

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?PostCode=LS1%204BT

  • returns summary information for one or more organisations where the postcode matches

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?PostCode=LS1

  • returns summary information for one or more organisations where partial on the outbound portion of the postcode matches

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?PrimaryRoleId=RO180

  • returns summary information for one or more organisations where the Role Code is flagged as primary on the organisation record

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?OrgRecordClass=rc2

  • returns summary information for one or more organisations where the RecordClass matches the string provided
  • valid options are rc1 for HSCOrg records and rc2 for HSCSite records

Summary Record Format

{"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": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/P3JX"
} ]
}

All parameters listed above can be combined to filter for records, e.g.

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?OrgRecordClass=rc2&LastChangeDate=2017-10-12

  • returns summary information for one or more organisations where the OrgRecordClass and LastChangeDate match

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.

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/X09?_format=xml

  • returns data as xml for a single organisation

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations?Name=Connecting&_format=xml

  • returns summary information for one or more organisations with the summary formatted as xml

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

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/Name=Trust&Limit=100

 

/sync returns a list of organisations optimised for bulk download

http://stable.ods.cis.spine2.ncrs.nhs.uk/api/sync?LastChangeDate=2017-10-25

  • returns limited summary information for one or more organisations
{"Organisations": [{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/P0MX"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/RT1"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/T2C9"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/P0F7"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/Y00626"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/RGQ"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/RDY"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/K82047"}, 
{"OrgLink": "http://stable.ods.cis.spine2.ncrs.nhs.uk/api/organisations/TP8G4"}]}