FHIR Patient

Base Path: /fhir/4.0/Patient

Version: 1.1.0

The Patient API allows you to retrieve FHIR Patient records using REST calls. This API allows you to:

  • Search for patient demographic information based on the patient's demographics.
  • Search for patient demographic information based on one of the patient's identifiers.
  • Retrieve demographic information for a patient based on the patient's FHIR ID.
  • Export a subset or all available or requested data for the patient
  • Monitor the status of an existing FHIR Bulk Export job.
  • Cancel a FHIR Bulk export job.
  • Download files generated by a FHIR Bulk Export job.

Methods

Get Patient information

GET /fhir/4.0/Patient/{id}

Returns demographics and other administrative information for a person receiving care or other health-related services using a query based on the FHIR ID. The data returned is subject to the privacy settings.


Parameters

Name

Type

Data Type

Description


Name:

id

required

Type:

path

Data Type:

string

Description:

The resource identifier of the Patient, which is part of the response when calling the Patient Search API.


Sample Value: IFAUCLJQGAYDAMJNHBAE6USJJ5HA



Name:

_format

optional

Type:

query

Data Type:

string

Description:

Controls whether the response is returned in JSON or XML format. If not supplied, then defaults to json.


Sample Value: json


Responses


application/json+fhir

200

Patient is found with given FHIR ID and patient resource is returned.


application/json+fhir

400

The given FHIR ID is empty or not valid.


application/json+fhir

404

No patient resource is found. This may be due to the requester of information having No Access privacy level for the patient resource.

Sample Requests

Retrieve a patient by patient id
curl -X GET "https://developer-solution/fhir/4.0/Patient/IFAUCLJQGAYDAMJNHBAE6USJJ5HA" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Search for a Patient

GET /fhir/4.0/Patient/

This method returns demographics and other administrative information for patients that match the supplied search criteria. It is possible to search for patients using either HTTP GET or POST methods. In some circumstances, it is possible to leak information when using a GET request, so it is generally recommended to use POST. Patient searches may be performed by supplying a combination of the following minimum criteria. Either:

  • Identifier
  • Or, Family name and one (or more) of the following:
    • Given name
    • Date of birth
    • Gender
  • Or, Name and one (or more) of the following:
    • Date of birth
    • Gender

When searching for patients with names with diacritics, you need to perform the search with HTTP Header "Content-Type: charset=utf-8".


Parameters

Name

Type

Data Type

Description


Name:

family

optional

Type:

query

Data Type:

string

Description:

The family name (last name) of the patient.


Sample Value: cardinal



Name:

given

optional

Type:

query

Data Type:

string

Description:

The given name (first name) of the patient.


Sample Value: jack



Name:

name

optional

Type:

query

Data Type:

string

Description:

The family name (last name) or the given name (first name) of the patient.


Sample Value: george



Name:

birthdate

optional

Type:

query

Data Type:

string

Description:

The patient's date of birth. The format of the birthdate value is yyyy-mm-dd.


Sample Value: 1949-11-12



Name:

gender

optional

Type:

query

Data Type:

string

Description:

Gender of the patient. Possible values are

  • male
  • female
  • other
  • unknown


Sample Value: female



Name:

identifier

optional

Type:

query

Data Type:

string

Description:

An identifier for the patient in the format, namespace|id


Sample Value: ORION|AAA-00001-8


Responses


application/json+fhir

200

The query was successfully processed. Any patients that match the given query parameter(s) are returned.


application/json+fhir

400

The query contains one or more invalid parameters. For example, using an incorrectly formatted patient birth date.


application/json+fhir

422

The search criteria is too generic. For example, using a wildcard (%) when searching by names.

Sample Requests

Search Patient by Demographics
curl -X GET "https://developer-solution/fhir/4.0/Patient/?family=cardinal&given=jack&gender=female" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Search for a Patient

POST /fhir/4.0/Patient/_search

Allows for the searching of demographics and other administrative information about a person receiving care or other health-related services. The patient search using the POST method is an alternative to the patient search using the GET method. The data returned is subject to the privacy settings. Patient searches may be performed by supplying a combination of the following minimum criteria. Either:

  • Identifier
  • Or, Family name and one (or more) of the following:
    • Given name
    • Date of birth
    • Gender
  • Or, Name and one (or more) of the following:
    • Date of birth
    • Gender

When searching for patients with names with diacritics, you need to perform the search with HTTP Header "Content-Type: charset=utf-8".


Parameters

Name

Type

Data Type

Description


Name:

Content-Type

required

Type:

header

Data Type:

string

Description:

Specifies how to encode the form data. The Content-Type value must be application/x-www-form-urlencoded


Sample Value: application/x-www-form-urlencoded



Name:

family

optional

Type:

formData

Data Type:

string

Description:

The family name (last name) of the patient.


Sample Value: cardinal



Name:

given

optional

Type:

formData

Data Type:

string

Description:

Filters the results to patients with a matching given name (first name)


Sample Value: jono



Name:

name

optional

Type:

formData

Data Type:

string

Description:

The family name (last name) or the given name (first name) of the patient.


Sample Value: cardinal



Name:

birthdate

optional

Type:

formData

Data Type:

string

Description:

Filters the results to patients with a matching date of birth. The format of the birthdate value is yyyy-mm-dd


Sample Value: 1949-11-12



Name:

gender

optional

Type:

formData

Data Type:

string

Description:

Gender of the patient. Possible values are

  • male
  • female
  • other
  • unknown


Sample Value: male



Name:

identifier

optional

Type:

formData

Data Type:

string

Description:

An identifier for the patient in the format, namespace|id


Sample Value: ORION|AAA-00001-8


Responses


application/json+fhir

200

The query was successfully processed. Any patients that match the given query parameter(s) are returned.


application/json+fhir

400

The query contains one or more invalid parameters. For example, using an incorrectly formatted patient birth date.


application/json+fhir

422

The search criteria is too generic. For example, using a wildcard (%) when searching by names.

Sample Requests

Search by Patient Identifier
curl -X POST "https://developer-solution/fhir/4.0/Patient/_search" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'identifier=ORION%7CAAA-00001-8'

Bulk Export for a patient

POST /fhir/4.0/Patient/$export

Exports all the requested (or all the available) FHIR R4 resources for all the requested patients. An export criteria parameters can be defined by a Parameters resource in the request body. If a criteria is specified the export will be limited to what is specified by the criteria parameters.


Parameters

Name

Type

Data Type

Description


Name:

paramater

required

Type:

body

Data Type:

Description:

Filters the export of Bulk data

  • parameter.name=_type : Defines the FHIR Resources to be included in the $export operation. This is a comma separated list of FHIR resource names.
  • parameter.name=_since : Defines the last updated date for the resources that are exported.
  • parameter.name=_outputFormat: Defines the format for the requested Bulk Data files to be generated. Only application/fhir+ndjson is supported
  • parameter.name=patient: A required and repeatable parameter with Patient FHIR ID references. The value for the 'patient' parameter can be with or without the resource name. e.g both "Patient/GYZGCNDDMRSWMQCPJBBVA" and "GYZGCNDDMRSWMQCPJBBVA" are supported
  • parameter.name=-include-sources : Defines for each FHIR resource which sources should be queried for the results. If -include-sources is specified, for the resource specified ONLY the specified sources will be searched. Note that the sources specified should be enabled.
  • parameter.name=-exclude-sources : Defines for a specific FHIR resource which sources should NOT be queried for the results. If -exclude-sources is specified, for the resource specified, the specified sources will NOT be searched. Note that the sources specified should be enabled.

Sample Payload:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "_outputFormat",
      "valueString": "application/fhir+ndjson"
    },
    {
      "name": "_type",
      "valueString": "Patient,Immunization,Procedure"
    },
    {
      "name": "_since",
      "valueInstant": "2022-01-01"
    },
    {
      "name": "patient",
      "valueString": "Patient/GYZGCNDDMRSWMQCPJBBVA"
    }
  ]
}




Name:

Accept

required

Type:

header

Data Type:

string

Description:

Specifies the format of the optional FHIR OperationOutcome resource response to the kick-off request. Only application/fhir+json is supported.


Sample Value: application/fhir+json



Name:

Prefer

required

Type:

header

Data Type:

string

Description:

Specifies whether the response is immediate or asynchronous. Only a value of respond-async is supported.


Sample Value: respond-async


Responses


application/json+fhir

202

The FHIR Bulk Export job was successfully triggered


application/json+fhir

400

Bad Request is returned in the following cases

  • FHIR Bulk is not enabled
  • One or more of the resources requested by the '_type' parameter is not available
  • One or more patients requested via the 'patient' parameter are not known or cannot be resolved
  • Invalid query parameter was requested
  • The patient parameter has at least one patient defined more than once.
  • The number of patients requested for export is too big (currently export is supported only for 20 or less patients)
  • The user doesn't have FULL ACCESS to ALL the patients requested to be exported.


application/json+fhir

401

The user is not authorized to perform the operation. This could be to the invalid login or due to not having enough access rights to perform the operation


application/json+fhir

429

The maximum of concurrent $export requests was reached. Currently 5 concurrent requests is supported.

Sample Requests

Export only Patient, Immunization and Procedure resources that were updated _since=2022-01-01
curl -X POST "https://developer-solution/fhir/4.0/Patient/$export" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-d '{"resourceType":"Parameters","parameter":[{"name":"_outputFormat","valueString":"application/fhir+ndjson"},{"name":"_type","valueString":"Patient,Immunization,Procedure"},{"name":"_since","valueInstant":"2022-01-01"},{"name":"patient","valueString":"Patient/GYZGCNDDMRSWMQCPJBBVA"}]}'

Retrieve a FHIR Bulk Export job status

GET /fhir/4.0/Patient/$export-poll-status

Obtain the status of a FHIR Bulk Patient Export Job using the GET method. The Full URL to poll status is provided in the Content-Location header that was returned by the Export method


Parameters

Name

Type

Data Type

Description


Name:

jobid

required

Type:

query

Data Type:

string

Description:

The Unique id of the export job. The job id and the path to poll the job status were returned in the Content-Location of the $export response.


Sample Value: 7fc54d79-2701-417b-a790-0e9a739d37ff


Responses


application/json+fhir

200

The export was completed.


application/json+fhir

202

The FHIR Bulk Export job is in progress.


application/json+fhir

400

Bad request is returned due to FHIR Bulk not enabled, invalid parameter, one or more patients in the group can not be resolved or unauthorised access.


application/json+fhir

404

The FHIR Bulk export files for the requested jobid have expired or were deleted, or not found


application/json+fhir

405

Only GET method is supported, and other http request (e.g POST) will result in Method Not Allowed error


application/json+fhir

500

The export operation failed due to internal error (e.g. failed to write to S3)

Sample Requests

Get the status for job id 7fc54d79-2701-417b-a790-0e9a739d37ff
curl -X GET "https://developer-solution/fhir/4.0/Patient/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Cancel a FHIR Bulk export job

DELETE /fhir/4.0/Patient/$export-poll-status

Cancel an existing FHIR Bulk Patient Export Job using the DELETE method. Use the poll status URL provided in the Content-Location header that was returned by the Export method to cancel the job.


Parameters

Name

Type

Data Type

Description


Name:

jobid

required

Type:

query

Data Type:

string

Description:

The Unique id of the export job. The job id and the path to poll the job status were returned in the Content-Location of the $export response.


Sample Value: 7fc54d79-2701-417b-a790-0e9a739d37ff


Responses


application/json+fhir

200

The job was cancelled.


application/json+fhir

400

Bad request due to invalid parameters or FHIR Bulk not enabled.


application/json+fhir

401

The user is not authorised to perform the login. In order to cancel a FHIR Bulk Patient export job the user should be a member of the 'FHIR Bulk Administrator' Group.


application/json+fhir

404

Job with the requested jobid cannot be found

Sample Requests

Cancel a Patient Export job
curl -X DELETE "https://developer-solution/fhir/4.0/Patient/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Download a FHIR Bulk Exported File

GET /fhir/4.0/Patient/$download

Download a file that was exported via a previous FHIR Bulk Patient Export request using the GET method. The Full URL of the file to be downloaded is provided in the $export-poll-status output or error array url links


Parameters

Name

Type

Data Type

Description


Name:

jobid

required

Type:

query

Data Type:

string

Description:

The Unique id of the export job. The Full URL of the file to be downloaded contains the jobid and is provided in the $export-poll-status output or error array url links for completed jobs


Sample Value: 7fc54d79-2701-417b-a790-0e9a739d37ff



Name:

resource

required

Type:

query

Data Type:

string

Description:

The FHIR Resource type that is contained in the file to be downloaded


Sample Value: Procedure



Name:

file

required

Type:

query

Data Type:

string

Description:

The file name to be downloaded


Sample Value: Patient_1.ndjson


Responses


application/json+fhir

200

The file is downloaded.


application/json+fhir

400

Bad request is returned due to FHIR Bulk not enabled, invalid parameter, one or more patients cannot be resolved, the user doesn't have FULL ACCESS to ALL the patients in the export request.


application/json+fhir

401

The user is not authorised for the operation.


application/json+fhir

404

The FHIR Bulk export job was not found.


application/json+fhir

405

Only GET method is supported, and other http request (e.g POST) will result in Method Not Allowed error.


application/json+fhir

500

The export operation failed due to internal error.

Sample Requests

Download a file containing Procedure resources exported
curl -X GET "https://developer-solution/fhir/4.0/Patient/$download?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff&file=Patient_1.ndjson" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='