API use case
The “Register a patient” use case creates a new temporary patient registration, or re-activates an existing “inactive” patient registration as a temporary patient registration within the GP practice system (Definition of a GP Connect active patient).
This specification describes a single use case. For complete details and background please see the Foundations capability bundle.
Security
- GP Connect utilises TLS Mutual Authentication for system level authorisation
- GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit and provenance details
Prerequisites
Consumer
The consumer system:
- SHALL have previously resolved the organisation’s FHIR endpoint Base URL through the Spine Directory Service
- SHALL have previously traced the patient’s NHS number using the Personal Demographics Service or an equivalent service
API usage
Request operation
FHIR relative request
POST /Patient/$gpc.registerpatient
FHIR absolute request
POST https://[proxy_server]/https://[provider_server]/[fhir_base]/Patient/$gpc.registerpatient
Request headers
Consumers SHALL include the following additional HTTP request headers:
Header | Value |
---|---|
Ssp-TraceID |
Consumer’s TraceID (i.e. GUID/UUID) |
Ssp-From |
Consumer’s ASID |
Ssp-To |
Provider’s ASID |
Ssp-InteractionID |
urn:nhs:names:services:gpconnect:fhir:operation:gpc.registerpatient-1 |
Example HTTP request headers:
POST http://gpconnect.aprovider.nhs.net/GP001/DSTU2/1/Patient/$gpc.registerpatient HTTP/1.1
User-Agent: .NET FhirClient for FHIR 1.2.0
Accept: application/fhir+json;charset=utf-8
Prefer: return=representation
Host: michaelm-pc
Content-Type: application/fhir+json;charset=utf-8
Content-Length: 289
Expect: 100-continue
Connection: Keep-Alive
Ssp-TraceID: 629ea9ba-a077-4d99-b289-7a9b19fd4e03
Ssp-From: 200000000115
Ssp-To: 200000000116
Ssp-InteractionID: urn:nhs:names:services:gpconnect:fhir:operation:gpc.registerpatient-1
Payload request body
The request payload is a Parameters resource conforming to the GPConnect-RegisterPatient-Operation-1 profile, with a single parameter of registerPatient
containing a Patient
resource profiled to the CareConnect-GPC-Patient-1 profile. This is the patient to be registered.
Within the Patient
resource:
- The following fields SHALL be populated as a minimum to allow the provider system to perform a PDS trace:
identifier
with the patient’s NHS numbername
includingfamily
andgiven
, with theuse
element set toofficial
.- No more than one instance of
name
whereuse
is set toofficial
SHALL be provided.
- No more than one instance of
birthDate
- The following fields SHOULD be populated, to create the patient’s record in the provider system:
gender
address
with the patient’s home address, with theuse
ofhome
. No more than one instance of thisuse
SHALL be populated.telecom
with the patient’s telephone number(s), withuse
ofhome
,work
ormobile
, andsystem
ofphone
. No more than one instance of eachuse
SHALL be populated.telecom
with the patient’s email address if available, withsystem
ofemail
. No more than one instance of this SHALL be populated.-
a single instance of
nhsCommunication
if available, specifically thelanguage
andinterpreterRequired
sub-elementsImportant: If the above “SHOULD” fields are not provided, the provider system will use demographics retrieved from PDS in order to create the patient’s record.
- The following fields MAY be populated in order to record temporary details known to the consuming system:
address
with temporary address details, with theuse
oftemp
. No more than one instance of thisuse
SHALL be populated.telecom
with temporary telephone details, with theuse
oftemp
andsystem
ofphone
. No more than one instance of this SHALL be populated.
- All other fields MUST NOT be populated.
On the wire a JSON serialised $gpc.registerpatient
request would look something like the following:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "registerPatient",
"resource": {
"resourceType": "Patient",
"meta": {
"profile": [
"https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1"
]
},
"identifier": [
{
"extension": [
{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSNumberVerificationStatus-1",
"valueCodeableConcept": {
"coding": [
{
"system": "https://fhir.nhs.uk/CareConnect-NHSNumberVerificationStatus-1",
"code": "01",
"display": "Number present and verified"
}
]
}
}
],
"system": "https://fhir.nhs.uk/Id/nhs-number",
"value": "9476719931"
}
],
"name": [
{
"use": "official",
"text": "Minnie DAWES",
"family": "Jackson",
"given": [
"Jane"
],
"prefix": [
"Miss"
]
}
],
"telecom": [
{
"system": "phone",
"value": "01454587554",
"use": "home"
},
{
"system": "phone",
"value": "07777111222",
"use": "mobile"
}
],
"gender": "female",
"birthDate": "1952-05-31",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Withings Lane",
"Shadwell"
],
"city": "Leeds",
"district": "West Yorkshire",
"postalCode": "LS18 1AE"
}
]
}
}
]
}
Provider system registration requirements
PDS requirements
Before registering the patient record on the local system, the provider SHALL retrieve the patient’s demographic record using a PDS Retrieval Query, and then:
-
Verify the patient’s NHS number according to the rules below:
- The NHS number within the request is considered verified if:
- The NHS number is found on PDS and the date of birth in the request exactly matches the date of birth held on PDS
- OR should 2 out of 3 parts of the date of birth match (YYYY or MM or DD) AND the first 3 characters of the first family name match and the initial character of the given match that held for the record on PDS.
-
If both of the above checks fail to find a match then the NHS number is treated as not verified
Note: The provider MAY use a PDS Cross Check Trace to perform this step, instead of using a PDS Retrieval and implementing the rules local locally.
If using the Cross Check Trace, the provider MUST then perform a subsequent Retrieval Query in order to return the patient’s full PDS record to supplement the patient’s demographics when creating or updating the patient’s record (in Local registration requirements).
- The NHS number within the request is considered verified if:
-
Check that the patient is not recorded as deceased on PDS
-
Check that patient’s PDS record does not have any of the following PDS flags:
- Invalid
- Sensitive
- Superseded
Duplicate record prevention
Before registering the patient record on the local system, the provider SHALL check the practice patient index for matching patients using the patient’s NHS number, and then:
-
If a matching patient record IS found:
-
and the matching patient record’s NHS number has not previously been traced or verified, it SHALL be verified using the rules shown above
- If the verification fails the registration SHALL be halted and an error returned to the consuming system
-
Then, if the matching patient record:
-
is active (i.e. a currently registered patient, of any registration type):
- The registration SHALL be halted and error is returned to the consumer
-
is inactive (i.e. a patient whose registration has lapsed of any registration type):
- The patient record SHALL be re-activated as a temporary patient
- Follow the Local registration requirements when updating the patient’s demographics
-
is recorded as deceased:
- The registration SHALL be halted and an error returned to the consuming system
-
-
-
If a matching patient record IS NOT found:
- A new temporary patient record SHALL be created
- Follow the Local registration requirements when creating the patient record
Local registration requirements
-
The patient record SHOULD be created or updated using:
- demographic details sent by the consumer
- supplemented by demographics returned from a PDS Retrieval Query where elements were omitted by the consumer or not part of the payload request message
- temporary address or temporary telecom details sent by the consumer SHOULD be marked with an end date aligned with the expiry date of the temporary record.
- If the provider system synchronises temporary patient records with PDS:
- an update SHALL NOT automatically be sent to PDS
- PDS synchronisation SHALL occur where a user is present during the next routine synchronisation event (for example, a receptionist opening the patient’s record)
- temporary address or temporary telecom details SHOULD be marked with an end date.
- a populated
Patient
resource representing the record created, or reactivated and updated, SHALL be returned to the consuming system shown in Payload response body below.
Error Handling
The provider system MUST return a GPConnect-OperationOutcome-1 resource that provides additional detail when one or more data field is corrupt or a specific business rule/constraint is breached.
The table below shown common errors that may be encountered during this API call, and the returned Spine error code. Please see Error handling guidance for additional information needed to create the error response, or to determine the response for errors encountered that are not shown below.
Errors returned due to parameter failure MUST include diagnostic information detailing the invalid parameter.
Error encountered | Spine error code returned |
---|---|
The Parameters resource passed by the consuming system including the embedded Patient resource is invalid, or does not include the minimum mandatory details |
INVALID_RESOURCE |
The NHS number could not be found on PDS, or verified against a PDS record | INVALID_PATIENT_DEMOGRAPHICS |
The patient is marked as deceased on PDS, or on the provider system | INVALID_PATIENT_DEMOGRAPHICS |
The registration request is for a sensitive patient | INVALID_PATIENT_DEMOGRAPHICS |
The PDS record contains an invalid or superseded flag | INVALID_NHS_NUMBER |
PDS is unavailable, or could not be contacted | INTERNAL_SERVER_ERROR |
The patient is already registered | DUPLICATE_REJECTED |
Request response
Response headers
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/fhir+json; charset=utf-8
Date: Sun, 07 Aug 2016 11:13:05 GMT
Content-Length: 1464
Payload response body
Provider systems:
- SHALL return a
200
OK HTTP status code on successful registration of the patient into the provider system. - SHALL include the URI of the relevant GP Connect
StructureDefinition
profile in thePatient.meta.profile
element of the returned resources. - SHALL return a searchset
Bundle
profiled to GPConnect-Searchset-Bundle-1 with aPatient
profiled to CareConnect-GPC-Patient-1 -
SHALL populate the
Patient
resource with details of the newly registered or re-activated patient - SHALL populate the following fields:
meta.profile
with the profile URIversionId
with the current version of thePatient
resource.identifier
with relevant business identifiers, including a minimum of the patient’s NHS numbername
birthDate
gender
address
where availabletelecom
where availablecontact
with the patient’s contacts - see Patient.contact population for further detailsregistrationDetails.preferredBranchSurgery
with a reference to aLocation
resource representing the patient’s preferred branch surgery (see Branch surgeries for more details), for a re-activated patient where availableregistrationDetails.registrationType
with the registration type used within the provider system. If an appropriate registration type is not available within the valueset then theOther
type SHALL be use and the name of the registration type SHOULD be added using thetext
element of the CodeableConceptnhsCommunication
with the patient’s language information, where availablemanagingOrganization
Note: this is the current organisation, as addressed by ODS code in the base URL, and NOT the patient’s registered practice which may be different
-
SHALL meet General FHIR resource population requirements populating all fields where data is available, excluding those listed below
- SHALL NOT populate the following fields:
ethnicCategory
religiousAffiliation
patient-cadavericDonor
residentialStatus
treatmentCategory
birthPlace
maritalStatus
multipleBirthBoolean
{
"resourceType": "Bundle",
"meta": {
"profile": [
"https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Searchset-Bundle-1"
]
},
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "2",
"meta": {
"versionId": "1469448000000",
"profile": [
"https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Patient-1"
]
},
"extension": [
{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-RegistrationDetails-1",
"extension": [
{
"url": "registrationPeriod",
"valuePeriod": {
"start": "2017-09-07T14:17:44+01:00"
}
},
{
"url": "registrationType",
"valueCodeableConcept": {
"coding": [
{
"system": "https://fhir.nhs.uk/CareConnect-RegistrationType-1",
"code": "T"
}
]
}
}
]
}
],
"identifier": [
{
"extension": [
{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-CareConnect-GPC-NHSNumberVerificationStatus-1",
"valueCodeableConcept": {
"coding": [
{
"system": "https://fhir.nhs.uk/CareConnect-NHSNumberVerificationStatus-1",
"code": "01",
"display": "Number present and verified"
}
]
}
}
],
"system": "https://fhir.nhs.uk/Id/nhs-number",
"value": "9476719931"
}
],
"active": true,
"name": [
{
"use": "official",
"text": "JACKSON Jane (Miss)",
"family": "Jackson",
"given": [
"Jane"
],
"prefix": [
"Miss"
]
}
],
"telecom": [
{
"system": "phone",
"value": "01454587554",
"use": "home"
},
{
"system": "phone",
"value": "07777111222",
"use": "mobile"
}
],
"gender": "female",
"birthDate": "1952-05-31",
"address": [
{
"use": "home",
"type": "physical",
"line": [
"1 Withings Lane",
"Shadwell"
],
"city": "Leeds",
"district": "West Yorkshire",
"postalCode": "LS18 1AE"
}
],
"managingOrganization": {
"reference": "Organization/14"
}
}
}
]
}
Examples
C#
var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
client.PreferredFormat = ResourceFormat.Json;
var parameters = new Parameters();
parameters.Add("registerPatient", new Patient
{
Active = true,
BirthDate = "1976-01-10",
Gender = (AdministrativeGender)Enum.Parse(typeof(AdministrativeGender),"Male"),
Name = new List<HumanName>
{
new HumanName()
{
Given = new[] {"Mike"},
Family = new[] {"Smith"},
Use = HumanName.NameUse.Usual
}
},
Identifier =
{
new Identifier("https://fhir.nhs.uk/Id/nhs-number","1234569999")
}
});
var resource = client.TypeOperation("gpc.registerpatient","Patient",parameters);
FhirSerializer.SerializeResourceToJson(resource).Dump();
Java
FhirContext ctx = FhirContext.forStu3();
IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1/");
Patient patient = new Patient();
patient.addIdentifier()
.setSystem("https://fhir.nhs.uk/Id/nhs-number")
.setValue("1234569999");
patient.addName()
.addFamily("Smith")
.addGiven("Mike")
.setUse(NameUseEnum.USUAL);
patient.setGender(AdministrativeGenderEnum.MALE);
patient.setBirthDate(new DateDt("1976-01-10"));
// Create the input parameters to pass to the server
Parameters inParams = new Parameters();
inParams.addParameter().setName("registerPatient").setValue(patient);
Parameters outParams = client
.operation()
.onType(Patient.class)
.named("gpc.registerpatient")
.withParameters(inParams)
.execute();
Bundle responseBundle = (Bundle) outParams.getParameter().get(0).getResource();
System.out.println(ctx.newXmlParser().setPrettyPrint(true).encodeResourceToString(responseBundle));