Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A004: Retrieve Reference Data

API

Request Type URL
GET /v1/ValueSet/{valueSetId}

Description

This read-only API lets a user access a pre-populated list of reference data. The NHS e-Referral Service uses these lists throughout. For example, a list of specialities. They support data accuracy and effective re-use. It retrieves a specific Value Set (Reference Dataset) by ID.

Reference Data

Reference data is classified into 2 types:

Static lists

These are documented on the FHIR server and can be looked up “manually” and stored once and for all in the database.

  • Values and associated business logic, such as adding/removing options (e.g. Priority, Request Type, Commissioning Type) - this means creating new business flows in the application, which means an upgrade is probably needed
  • Standard FHIR lists

Dynamic lists

These are “gettable” from e-RS; third parties should handle them as dynamic data, i.e. adding/removing values should not require a software upgrade.

  • The only dynamic list we have so far is Specialty
  • The next forthcoming dynamic list is Clinic Type
  • In future we will be adding Rebooking Reasons/Cancellation Reasons and other dynamics lists

Input

Currently applicable values for the {valueSetId}:

Value Set ID Description
SPECIALTY Specialties defined in e-RS

Provide ASID of the end-point system and equivalent Session Key generated for the SSO Token-ID.

Example

XAPI_ASID:200000000220
Content-Type:application/json+fhir
HTTP_X_SESSION_KEY:pro-xapi-session_5a399946-23c5-4543-8c4f-7eca38732a58

Output

A Value Set Resource profiled specifically for the given valueSetId. This will include the requested coding system with its available codes. The response code 200 (OK) is returned.

Example

{
    "id": "SPECIALTY",
    "meta": {
        "profile": [
            "http://fhir.nhs.uk/StructureDefinition/ers-valueset-1"
        ]
    },
    "resourceType": "ValueSet",
    "status": "active",
    "publisher": "HSCIC",
    "date": "2017-07-28",
    "description": "Specialties defined in e-RS",
    "codeSystem": {
        "system": "http://fhir.nhs.uk/ValueSet/ers-specialty-1",
        "concept": [
            {
                "extension": [
                    {
                        "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-effectivefromdate-1",
                        "valueDateTime": "2004-06-01T00:00:00.000Z"
                    }
                ],
                "code": "2WW",
                "display": "2WW",
                "designation": {
                    "value": "9901"
                }
            },

            {
                "extension": [
                    {
                        "url": "http://fhir.nhs.uk/StructureDefinition/extension-ers-effectivefromdate-1",
                        "valueDateTime": "2004-06-01T00:00:00.000Z"
                    }
                ],
                "code": "UROLOGY",
                "display": "Urology",
                "designation": {
                    "value": "101"
                }
            }
        ]
    }
}

Notes

Consuming application must have a valid session in order to access this endpoint.


All content is available under the Open Government Licence v3.0, except where otherwise stated