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:
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.
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
200
Patient is found with given FHIR ID and patient resource is returned.
400
The given FHIR ID is empty or not valid.
404
No patient resource is found. This may be due to the requester of information having No Access privacy level for the patient resource.
curl -X GET "https://developer-solution/fhir/4.0/Patient/IFAUCLJQGAYDAMJNHBAE6USJJ5HA" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
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:
When searching for patients with names with diacritics, you need to perform the search with HTTP Header "Content-Type: charset=utf-8".
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
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
200
The query was successfully processed. Any patients that match the given query parameter(s) are returned.
400
The query contains one or more invalid parameters. For example, using an incorrectly formatted patient birth date.
422
The search criteria is too generic. For example, using a wildcard (%) when searching by names.
curl -X GET "https://developer-solution/fhir/4.0/Patient/?family=cardinal&given=jack&gender=female" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
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:
When searching for patients with names with diacritics, you need to perform the search with HTTP Header "Content-Type: charset=utf-8".
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
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
200
The query was successfully processed. Any patients that match the given query parameter(s) are returned.
400
The query contains one or more invalid parameters. For example, using an incorrectly formatted patient birth date.
422
The search criteria is too generic. For example, using a wildcard (%) when searching by names.
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'
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.
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 supportedparameter.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 supportedparameter.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
202
The FHIR Bulk Export job was successfully triggered
400
Bad Request is returned in the following cases
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
429
The maximum of concurrent $export
requests was reached. Currently 5 concurrent requests is supported.
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"}]}'
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
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
200
The export was completed.
202
The FHIR Bulk Export job is in progress.
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.
404
The FHIR Bulk export files for the requested jobid have expired or were deleted, or not found
405
Only GET method is supported, and other http request (e.g POST) will result in Method Not Allowed error
500
The export operation failed due to internal error (e.g. failed to write to S3)
curl -X GET "https://developer-solution/fhir/4.0/Patient/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
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.
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
200
The job was cancelled.
400
Bad request due to invalid parameters or FHIR Bulk not enabled.
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.
404
Job with the requested jobid cannot be found
curl -X DELETE "https://developer-solution/fhir/4.0/Patient/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
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
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
200
The file is downloaded.
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.
401
The user is not authorised for the operation.
404
The FHIR Bulk export job was not found.
405
Only GET method is supported, and other http request (e.g POST) will result in Method Not Allowed error.
500
The export operation failed due to internal error.
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='