Search loading...


Explore and Make use of Nationally Defined Messaging APIs


Read Subscription

How to read a subscriptions


In addition to the guidance on this page the guidance and requirement on the Generic Subscription API Requirements page SHALL be followed when using the NEMS subscription API.

Retrieving a Subscription

To retrieve a specific subscription, the client will need to use the ID that was allocated to the subscription when it was created (see Create Subscription)

HTTP Request

To read a subscription by its logical ID, a standard FHIR read operation can be used:

GET /Subscription/[Subscription_Logical_ID]

Request Headers

The system calling the API MUST include the following HTTP request headers when making the call to the Read Subscription API endpoint:

Header Description
fromASID ASID of the system calling the Subscription API
toASID ASID of the NEMS service
InteractionID Fixed value: urn:nhs:names:services:clinicals-sync:SubscriptionsApiGet

Additional information about standard headers and endpoints is available in the Spine Core specification.

Error Handling

If an error occurs while trying to process the request the NEMS will return a HTTP error code along with an OperationOutcome FHIR resource within the payload. The OperationOutcome resource will contain one of the Spine ErrorOrWarning Codes and conform to the structure set out in the Spine Core FHIR specification.


Where a subscription is found for the logical ID the response will be:

  • a HTTP status code of 200
  • a payload containing the requested Subscription resource. The subscription resource returned SHALL conform to the EMS-Subscription-1 FHIR profile.

Retrieve Subscription Example

Date: Sat, 26 May 2018 12:34:11 GMT
Last-Modified: Sat, 26 May 2018 00:00:00 GMT
Content-type: application/xml+fhir

	<id value="ea0a485187204b49b978bdcf7102388c"/>
		<lastUpdated value="2018-05-26T00:00:00+00:00"/>
		<profile value=""/>
	<status value="active"/>
		<system value="url"/>
		<value value=""/>
		<use value="work"/>
	<reason value="Health visiting service responsible for Leeds"/>
	<criteria value="/Bundle?type=message&amp;Organization.identifier=X2458&amp;MessageHeader.event=pds-birth-notification-1&amp;MessageHeader.event=pds-change-of-address-1&amp;MessageHeader.event=pds-change-of-gp-1&amp;MessageHeader.event=pds-person-death-1"/>
		<type value="message"/>
		<endpoint value="Mailbox1234"/>
Tags: fhir

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