MediRecords FHIR Implementation Guide
20221128 - ci-build


Patient

The MediRecords FHIR API supports the following Patient operations.

GET {API_URL}/v1/Patient

This API interface enables the client to search Patient instances from MediRecords repository. This is in compliance with the MediRecords Patient profile.

Query Parameters    
_count number Instruct the server regarding how many resources should be returned in a single page
active boolean Whether the patient record is active
address-city string A city specified in an address
birthdate date The patient’s date of birth
family string Last Name of the Patient
gender token Gender of the patient
given string A portion of the given name of the patient
identifier token A patient identifier with a system and value in the form <system>|<identifier>, and URL encoded as shown in the example below.
Example 1:
identifier=http://ns.electronichealth.net.au/id/medicare-number%7C32788511952.
The following system uris are supported:
* MCN - http://ns.electronichealth.net.au/id/medicare-number
* IHI - http://ns.electronichealth.net.au/id/hi/ihi/1.0
* PT - urn:uuid:<tenant-id>

The :of-type modifier may be used to search by identifier type using the form <system>|<code>|<identifier>
Example 2:
identifier:of-type=http://terminology.hl7.org/CodeSystem/v2-0203%7CPT%7C123456X43
organization reference The organization that is the custodian of the patient record. It’s the default practice reference where the patient details are created.
phone token A value in a phone contact
telecom token The value in any kind of telecom details of the patient. Use in conjunction with phone parameter to search Patient with home, work or mobile phone.
  • When searched with ‘identifier’, a Patient’s ‘family’, ‘birthdate’ and ‘gender’ must be provided in the search criteria.

  • When searched with ‘phone’, ‘telecom’ must be provided in the search criteria. For example:
    /Patient?phone=0412030741&telecom=mobile
    NOTE: the above use of telecom is not compliant with FHIR specification

  • By default, only active patients will be returned in search results. Use parameter &active=false to retreive inactive patients.

Request Headers  
X-Request-Id A unique id to for the request/response assigned by either client or server. The expected format is UUID. If the client doesn’t supply this id, it is expected that server SHALL assign one.

Response

The server returns matching Patient instances in a Bundle that the logged-in user has access to. If no search criteria is provided, then all Patient instances that the logged-in user has access to will be returned.

In an error situation, server SHALL return OperationOutcome detailing the error with the appropriate HTTP Error code as follows.

Status Text
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Read

GET {API_URL}/v1/Patient/{id}

This API interface enables the client to read an Patient resource from MediRecords repository which is compliant with the MediRecords Patient profile.

Request Parameters  
id The logical id of the Patient resource

Response

In an error situation, server SHALL return OperationOutcome detailing the error with the appropriate HTTP Error code as follows.

Status Text
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Create

POST {API_URL}/v1/Patient

This API interface enables the client to create a Patient resource in MediRecords repository which is compliant with the MediRecords Patient profile.

Request Parameters  
_format This parameter allows a client to override the accept header value when it is unable to set it correctly due to internal limitations (e.g. XSLT usage). the values xml, text/xml, application/xml, and application/fhir+xml SHALL be interpreted to mean the XML format, the codes json, application/json and application/fhir+json SHALL be interpreted to mean the JSON format. The _format parameter does not override the Content-Type header for the type of the body of a POST request
Request Headers  
Prefer The client can indicate how the response can be returned. return=minimal indicates that the client asks to return no body. return=representation indicates that the client asks to return the full resource. return=OperationOutcome indicates that the client asks server to return an OperationOutcome resource containing hints and warnings about the operation rather than the full resource
X-Request-Id A unique id to for the request/response assigned by either client or server. The expected format is UUID. If the client doesn’t supply this id, it is expected that server SHALL assign one.

Request Body

Request body that creates a new Patient resource

Response

In an error situation, server SHALL return OperationOutcome detailing the error with the appropriate HTTP Error code as follows.

Status Text  
201 Created The response to this depends on what is specified in “Prefer” header or what is server’s default behaviour. By default this returns the requested Patient instance with the logical id populated in it.
400 Bad Request Resource could not be parsed or failed basic FHIR validation rules
401 Unauthorized  
403 Forbidden  
404 Not Found Resource type not supported, or not a FHIR end-point
409 Conflict  
422 Unprocessable Entity The proposed resource violated applicable FHIR profiles or server business rules.
500 Internal Server Error  

Update

PUT {API_URL}/v1/Patient/{id}

This API interface enables the client to update a specific Patient resource instance existed in MediRecords repository which is compliant with the MediRecords Patient profile.

Request Parameters  
id The logical id of the Patient resource
Request Headers  
X-Request-Id A unique id to for the request/response assigned by either client or server. The expected format is UUID. If the client doesn’t supply this id, it is expected that server SHALL assign one.

Request Body

Request body that updates an existing Patient record details

Response

In an error situation, server SHALL return OperationOutcome detailing the error with the appropriate HTTP Error code as follows.

Status Text
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Unprocessable Entity
500 Internal Server Error

Delete

DELETE {API_URL}/v1/Patient/{id}

This API interface enables the client to delete a specific Patient resource instance from MediRecords repository.

Request Parameters  
id The logical id of the Patient resource
Request Headers  
X-Request-Id A unique id to for the request/response assigned by either client or server. The expected format is UUID. If the client doesn’t supply this id, it is expected that server SHALL assign one.

Response

In an error situation, server SHALL return OperationOutcome detailing the error with the appropriate HTTP Error code as follows.

Status Text
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Webhook

The following table provides the FHIR Webhook event types generated for the Patient resource.

Hub Event Application Trigger Event  
patient.created Occurs whenever a new patient record is created Example
patient.updated Occurs whenever a patient record is updated  
Bundle
  Patient (1) 
  PractitionerRole (0..1) 
  Practitioner (0..1) 
  Organization (0..2)
     
patient.deleted Occurs whenever a patient record is deleted Example
Bundle
  request (1)
    url: DELETE Patient/{id}