Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A010: Patient Service Search

Status: Beta

API URL

Base URL (Dev3): https://api.dev3.ers.ncrs.nhs.uk/ers-api/

Method URL Authentication
POST STU3/v1/HealthcareService/$ers.searchHealthcareServicesForPatient Session Token (Details)

Description

As a Referring Clinician (/Administrator) needing to refer a patient
I want to search for services that are appropriate for my patient
So that I can create a shortlist of services where my patient can be referred to.

Prerequisite Operations

If using the filter on specialty, the value provided must be a valid code obtained via the Get Reference Data (A004) endpoint.

Request Operation

Request Header

Field Name Value
XAPI_ASID The “Accredited System ID” issued to the third party
HTTP_X_SESSION_KEY The session key generated by the Create Session endpoint (A001)
Accept application/fhir+json
Content-Type application/fhir+json

Request Body

The Operation Definition for this endpoint is available on the FHIR server: ers.patientServiceSearch

Parameter Name Cardinality Type Notes
patient 1..1 Identifier The master NHS Number for the patient
requestType 1..1 Code  
referringClinician 0..1 Identifier If the logged in user is an RCA (and only in this case) they need to specify the referring clinician on whose behalf they are operating, in the context of the current referral
SearchCriteria 1..1 Resource The StructureDefintion of this Resource is: eRS-ServiceSearchCriteria-Parameters-1
restrictedService 0..1 Reference  
sortBy 1..1 Code  

Examples:

Request Header
  XAPI_ASID:200000000347
  HTTP_X_SESSION_KEY:pro-api-session:9f0ee57a-41a6-4a6b-b50c-d50e61859c81
  Accept:application/fhir+json
  Content-Type:application/fhir+json
  
Request Body
  {
  "resourceType": "Parameters",
  "meta": {
    "profile": [
    "https://fhir.nhs.uk/STU3/OperationDefinition/eRS-PatientServiceSearch-Operation-1"
    ]
  },
  "parameter": [{
    "name": "patient",
    "valueIdentifier": {
      "system": "http://fhir.nhs.net/Id/nhs-number",
      "value": "1234567890"
    }
  },
  {
    "name": "requestType",
    "valueCoding": {
      "system": "https://fhir.nhs.uk/STU3/ValueSet/eRS-RequestType-1",
      "code": "APPOINTMENT_REQUEST"
    }
  },  {
    "name": "searchCriteria",
    "resource": {
      "resourceType": "Parameters",
      "meta": {
        "profile": [
        "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-ServiceSearchCriteria-Parameters-1"
        ]
      },
      "parameter": [{
        "name": "priority",
        "valueCoding": {
          "system": "https://fhir.nhs.uk/STU3/ValueSet/eRS-Priority-1",
          "code": "ROUTINE"
        }
      }, {
        "name": "specialty",
        "valueCoding": {
          "system": "https://fhir.nhs.uk/STU3/ValueSet/eRS-Specialty-1",
          "code": "EAR_NOSE_THROAT"
        }
      }, {
        "name": "clinicType",
        "valueCoding": {
          "system": "https://fhir.nhs.uk/STU3/ValueSet/eRS-ClinicType-1",
          "code": "EAR"
        }
      }, {
        "name": "namedClinician",
        "valueIdentifier": {
          "system": "http://fhir.nhs.net/Id/sds-user-id",
          "value": "555021146102"
        }
      },	{
        "name": "organisation",
        "valueIdentifier": {
          "system": "https://directory.spineservices.nhs.uk/STU3/Organization/",
          "value": "R01"
        }
      }, {
        "name": "indicativeAppointmentWaitTimeLimit",
        "valueUnsignedInt":"10"
      }, {
        "name": "postcode",
        "valueString":"DN39 6SW"
      }, {
        "name": "distanceLimit",
        "valueUnsignedInt":"100"
      }, {
        "name": "commissioningProvisioning",
        "valueCoding": {
          "system": "https://fhir.nhs.uk/STU3/ValueSet/eRS-CommissioningProvisioning-1",
          "code": "ALL_AVAILABLE_FOR_BOOKING"
        }
      },
      {
        "name": "ageAndGenderAppropriate",
        "valueBoolean":true
      }]
    }
  }, {
    "name": "sortBy",
    "valueCoding": {
      "system": "https://fhir.nhs.uk/STU3/ValueSet/eRS-SortBy-1",
      "code": "DISTANCE"
    }
  }]
  }
  


Response

Success

HTTP Status code 200 (OK) is returned. The response body contains the list of services (if any) that match the search criteria provided in the format of an eRS-FetchServices-List-1

Example:

Response Body
  {
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-FetchServices-List-1"
        ]
    },
    "resourceType": "List",
    "status": "current",
    "mode": "snapshot",
    "entry": [
        {
            "extension": [
                {
                    "extension": [
                        {
                            "url": "restricted",
                            "valueBoolean": false
                        },
                        {
                            "url": "unaccredited",
                            "valueBoolean": false
                        },
                        {
                            "url": "displayProminently",
                            "valueBoolean": false
                        },
                        {
                            "url": "distance",
                            "valueUnsignedInt": 51
                        },
                        {
                            "url": "indicativeAppointmentWaitTime",
                            "valueUnsignedInt": 1
                        }
                    ],
                    "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ServiceSearch-ListItem-1"
                }
            ],
            "item": {
                "extension": [
                    {
                        "extension": [
                            {
                                "url": "serviceName",
                                "valueString": "SA-DEV3 ENT Service 001 - DBS - RL and CAS"
                            },
                            {
                                "url": "specialty",
                                "valueCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "https://fhir.nhs.uk/STU3/ValueSet/eRS-Specialty-1",
                                            "code": "EAR_NOSE_THROAT"
                                        }
                                    ]
                                }
                            },
                            {
                                "url": "genderTreated",
                                "valueCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-GenderTreated-1",
                                            "code": "MALE_AND_FEMALE"
                                        }
                                    ]
                                }
                            },
                            {
                                "url": "bookableType",
                                "valueCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-BookableType-1",
                                            "code": "DIRECTLY_BOOKABLE"
                                        }
                                    ]
                                }
                            },
                            {
                                "url": "supportedAppointmentType",
                                "valueCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AppointmentType-1",
                                            "code": "FIRST_OUTPATIENT"
                                        }
                                    ]
                                }
                            },
                            {
                                "url": "referralLetterRequired",
                                "valueBoolean": true
                            },
                            {
                                "url": "location",
                                "valueReference": {
                                    "reference": "https://ers/Location/7128805",
                                    "display": "R01 TRUST SITE 01"
                                }
                            },
                            {
                                "url": "linkToNHSWebsite",
                                "valueString": "https://www.nhs.uk/service-search/chooseandbook?serviceId=6473511"
                            },
                            {
                                "url": "supportedRequestFlowType",
                                "valueCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-RequestFlowType-1",
                                            "code": "ADVICE_AND_GUIDANCE_REQUEST"
                                        }
                                    ]
                                }
                            },
                            {
                                "url": "supportedRequestFlowType",
                                "valueCodeableConcept": {
                                    "coding": [
                                        {
                                            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-RequestFlowType-1",
                                            "code": "APPOINTMENT_REQUEST"
                                        }
                                    ]
                                }
                            },
                            {
                                "url": "exclusions",
                                "valueString": "Exclusions - Tongue"
                            },
                            {
                                "url": "conditionsTreated",
                                "valueString": "Conditions - Ear / Nose / Throat"
                            },
                            {
                                "url": "suggestedInvestigations",
                                "valueString": "Suggested - Ear Tests"
                            }
                        ],
                        "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-ServiceSummaryView-1"
                    }
                ],
                "reference": "HealthcareService/6473511"
            }
        }
    ]
  }
  


Failure

If an error occurs, the relating HTTP status code will be returned in the header. Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below.

issue.details.code Description
FIELD_NOT_PERMITTED A referring clinician is provided when the logged in user is not an RCA; or: one of the following occurs: the distance limit is specified when the postcode is not provided, the IWT limit is specified when the priority is TWO_WEEK_WAIT or the clinic type is specified when the specialty is not provided
INAPPROPRIATE_VALUE The value of commissioning provisioning is ALL_SERVICES (this value is not supported)
NO_REG_GP_PRACTICE The patient provided was found not to have a registered GP practice. The patient is not eligible to be referred via e-RS while this problem persists
ORGANISATION_IS_CLOSED The organisation identifier supplied corresponds to an organisation that is closed
ORGANISATION_NOT_APPROPRIATE The organisation identifier supplied corresponds to an organisation of a type other than ‘Service location’ and ‘Service providing organisation’
PATIENT_ERROR There was a problem with the patient’s record in SDS. The patient is not eligible to be referred via e-RS while this problem persists
REFERENCE_NOT_FOUND An entity referenced (e.g. the patient, the postcode, the organisation or a clinician) is not found
REFERENCED_USER_IS_NOT_ACTIVE The SDS user provided as the referring clinician or the named clinician is found to be not active in SDS
REFERENCED_USER_IS_NOT_RC The SDS user provided as the referring clinician does not actually have the Referring Clinician business function in e-RS
REFERENCED_USER_IS_NOT_SPC The SDS user provided as the named clinician does not actually have the Service Provider Clinician business function in e-RS
REFERENCED_USER_NOT_IN_ORG The referring clinician provided does not belong to the same organisation as the logged in user
SERVICE_IS_NOT_RESTRICTED The service provided is not restricted for the user
SERVICE_NOT_IN_RESULTS The restricted service provided is not compatible with the search criteria
VALUE_IS_REQUIRED A referring clinician is not provided when the logged in user is an RCA; or: one of the following three is not provided: the pair specialty + clinic type, the clinical term¬ or the named clinician

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