FGM Create Flag/ Response FHIR Messaging API.


To use this FHIR Messaging API, the requester:

  • SHALL have gone through accreditation and received an endpoint certificate and associated ASID (Accredited System ID) for the client system.
  • SHALL have authenticated the user using national smartcard authentication, and obtained a ticket and the UUID from the user’s smartcard
  • SHALL have previously traced the patient’s NHS Number using PDS or an equivalent service.

FGM Create

FGM Create Request

For all FGM Create request interactions the payload MUST include these FGM FHIR profiles:

The FGM Create request payload MAY include the FGM FHIR profile:

FGM Create Request

POST /fhir/fgm/create HTTP/1.1
Host: msg.int.spine2.ncrs.nhs.uk
SOAPAction: "urn:nhs:names:services:clinicals-sync:FGMCreate_1_0"
Content-Length: 3305
Content-Type: text/xml; charset=utf-8
Connection: close
  • Additional examples are available here - XML

Create Response


  • SHALL return a 201 Created HTTP status code on successful execution of the interaction.
  • SHALL return a Bundle of type message that conforms to the spine-message-bundle-1-0 profile;
  • SHALL return a MessageHeader resource that conforms to the spine-Response-messageheader-2-0 profile.

Spine 2 will return:

HTTP/1.1 201 Created
Server: nginx/1.10.1
Date: Fri, 06 Jan 2017 09:17:00 GMT
Content-Type: application/xml+fhir;charset=utf-8
Content-Length: 948
Connection: close


  • SHALL return one of the below HTTP status error codes with an OperationOutcome resource that conforms to the spine-operationoutcome-1 profile if the create flag cannot be executed.
  • The below table summarises the types of error that could occur, and the HTTP response codes, along with the values to expect in the OperationOutcome response body.
HTTP Code issue-severity issue-type Details.Code Details.Display Orignal codes
404 error not-found NO_RECORD_FOUND No Record Found FGM-0001
400 error invalid INVALID_NHS_NUMBER Invalid NHS number FGM-0002
400 error invalid PATIENT_OVER_18 Patient is over 18 FGM-0003
400 error invalid INVALID_PARAMETER Invalid parameter FGM-0004
422 warning informational FLAG_ALREADY_SET Flag value was already set FGM-0005
400 error structure MESSAGE_NOT_WELL_FORMED Message not well formed FGM-9999
403 error forbidden ASID_CHECK_FAILED The sender or receiver’s ASID is not authorised for this interaction 300
  • The error codes are defined in the spine-response-code-2-0 ValueSet.
  • Error INVALID_NHS_NUMBER would occur if the NHS number being requested in the search request is invalid.
  • Error ASID_CHECK_FAILED comes from the old SOAP error for Access Denied with is already used throughout Spine when the endpoint lookup fails.

If the NHS number used in the create request is invalid the Spine 2 will return:

HTTP/1.1 400 Bad Request
Server: nginx/1.10.1
Date: Fri, 06 Jan 2017 09:17:00 GMT
Content-Type: application/xml+fhir;charset=utf-8
Content-Length: 948
Connection: close
  • Additional examples are available here - XML

Example Code


FhirContext ctx = FhirContext.forDstu2();
Bundle bndl = CreateFGMFlagXML.createBundle();
MessageHeader mh = CreateFGMFlagXML.createMessageHeader();
Flag flag = CreateFGMFlagXML.createFlag();
Practitioner prac = CreateFGMFlagXML.createPractitioner();
Organization orgn = CreateFGMQueryv2.createOrganization();
final Entry entryBundle = bndl.addEntry();		
final Entry entryMh = bndl.addEntry();
final Entry entryFlag = bndl.addEntry();
final Entry entryPrac = bndl.addEntry();
final Entry entryOrg = bndl.addEntry();
String output = ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(bndl);
String serverBaseUrl = "http://fhirtest.uhn.ca/baseDstu2";
IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);
MethodOutcome outcome = client.create().resource(bndl).execute();
Tags: development