Base Path: /fhir/4.0/Group
Version: 1.0.0
The FHIR Group API allows you to to retrieve information for defined groups. The endpoint provides the ability to:
The data returned in this API is subject to privacy and permissions settings, refer to the Working with Privacy guide to learn how this might affect your application.
This API is based on the R4 release of the FHIR standard, for more information on this API refer to the official FHIR documentation.
GET /fhir/4.0/Group/
This method returns all available Group resources. Optionally filtering by search criterias.
Name
Type
Data Type
Description
Name:
member
optional
Type:
query
Data Type:
string
Description:
Filters the groups that the member is in. The parameter value is a reference to the entity that is a member of the group.
Sample Value: Patient/GYZGCNDDMRSWMQCPJBBVA
Name:
type
optional
Type:
query
Data Type:
string
Description:
Filters the groups to those of a specified type. Possible values are
person
animal
practitioner
device
medication
substance
Sample Value: person
Name:
-name
optional
Type:
query
Data Type:
string
Description:
Filters the groups to those with the specified name.
Sample Value: the-smith-family
Name:
-include-sources
optional
Type:
query
Data Type:
array
Description:
The -include-sources parameter defines which sources should be queried for the results.
Note: Either -include-sources
or -exclude-sources
parameter can be specified, not both. If -include-sources is specified, ONLY the specified sources will be searched. Note that the sources specified should be enabled.
Sample Value: Orion%20Health%E2%84%A2%20R4%20Group%20Store
Name:
-exclude-sources
optional
Type:
query
Data Type:
array
Description:
The -exclude-sources parameter defines which sources should NOT be queried for the results.
Note: Either -include-sources
or -exclude-sources
parameter can be specified, not both. If -exclude-sources is specified, the specified sources will NOT be searched. Note that the sources specified should be enabled.
Sample Value: Orion%20Health%E2%84%A2%20R4%20Group%20Store
Name:
_format
optional
Type:
query
Data Type:
string
Description:
Media type of the response. It takes precedence over the accept header. Possible values are json
and xml
. The default value is set to json
.
Default Value: xml
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response. Possible values are application/json
and application/xml
. The default value is set to application/xml
.
Default Value: application/xml
Sample Value: application/json
200
Returns a FHIR Bundle containing 0..* Group resources.
400
This response code is returned when the query is invalid e.g. an invalid parameter or a partial token in the search.
curl -X GET "https://developer-solution/fhir/4.0/Group/?member=Patient/GYZGCNDDMRSWMQCPJBBVA&type=person" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
POST /fhir/4.0/Group/
This method creates a Group.
Name
Type
Data Type
Description
Name:
Content-Type
required
Type:
header
Data Type:
string
Description:
Specifies how to encode the form data. Possible values are application/json
and application/xml
.
Sample Value: application/json
Name:
Group
required
Type:
body
Data Type:
Description:
The group resource fields. Must have the following fields populated: Group.type
and Group.actual
.
Sample Payload:
{
"resourceType": "Group",
"active": true,
"actual": true,
"type": "person",
"name": "my-group-name",
"member": [
{
"entity": {
"reference": "Patient/GYZGCNDDMRSWMQCPJBBVA"
}
},
{
"entity": {
"reference": "Patient/MYYDEOJSHAYTAQCPJBBVA"
}
}
]
}
201
This response code is returned when a new Group is created successfully. The Group FHIR Id is in the header.
400
This response code is returned when the query is invalid. e.g. Group.actual or Group.type are not defined.
401
This response code is returned when the user is not authorised to perform the operation. This could be due to invalid login or not having enough access rights to perform the operation. In order to create or update groups the user should either be a member of the "FHIR Group Administrator" or the "FHIR Write Administrator" Group.
curl -X POST "https://developer-solution/fhir/4.0/Group/" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-d '{"resourceType":"Group","active":true,"actual":true,"type":"person","name":"my-group-name","member":[{"entity":{"reference":"Patient/GYZGCNDDMRSWMQCPJBBVA"}},{"entity":{"reference":"Patient/MYYDEOJSHAYTAQCPJBBVA"}}]}'
POST /fhir/4.0/Group/_search
This method returns all available groups. Optionally filtering by the specified search criteria.
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:
member
optional
Type:
formData
Data Type:
string
Description:
Filters the groups that the member is in. The parameter value is a reference to the entity that is a member of the group.
Sample Value: Patient/GYZGCNDDMRSWMQCPJBBVA
Name:
type
optional
Type:
formData
Data Type:
string
Description:
Filters the groups to those of a specified type. Possible values are
person
animal
practitioner
device
medication
substance
Sample Value: medication
Name:
-name
optional
Type:
formData
Data Type:
string
Description:
Filters the groups to those with the specified name.
Sample Value: the-Smith-family
Name:
-include-sources
optional
Type:
formData
Data Type:
array
Description:
The -include-sources parameter defines which sources should be queried for the results.
Note: Either -include-sources
or -exclude-sources
parameter can be specified, not both. If -include-sources is specified, ONLY the specified sources will be searched. Note that the sources specified should be enabled.
Sample Value: Orion%20Health%E2%84%A2%20R4%20Group%20Store
Name:
-exclude-sources
optional
Type:
formData
Data Type:
array
Description:
The -exclude-sources parameter defines which sources should NOT be queried for the results.
Note: Either -include-sources
or -exclude-sources
parameter can be specified, not both. If -exclude-sources is specified, the specified sources will NOT be searched. Note that the sources specified should be enabled.
Sample Value: Orion%20Health%E2%84%A2%20R4%20Group%20Store
Name:
_format
optional
Type:
header
Data Type:
string
Description:
Media type of the response. It takes precedence over the accept header. Possible values are json
and xml
.
Default Value: xml
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response. Possible values are application/json
and application/xml
.
Default Value: application/xml
Sample Value: application/json
200
Returns a FHIR Bundle containing 0..* Group resources.
400
This response code is returned when the query is invalid e.g. an invalid parameter or a partial token in the search.
curl -X POST "https://developer-solution/fhir/4.0/Group/_search" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d '-name=the-Smith-family'
GET /fhir/4.0/Group/{id}
This method returns the Group resource matching the requested resource ID.
Name
Type
Data Type
Description
Name:
id
required
Type:
path
Data Type:
string
Description:
The ID of the Group resource.
Sample Value: GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ
Name:
_format
optional
Type:
query
Data Type:
string
Description:
Media type of the response. It takes precedence over the accept header. Possible values are json
and xml
.
Default Value: xml
Sample Value: json
Name:
Accept
optional
Type:
header
Data Type:
string
Description:
Media type of the response. Possible values are application/json
and application/xml
.
Default Value: application/xml
Sample Value: application/json
200
Returns an Group resource matching the requested resource ID.
404
No Group resource found with the requested resource ID.
curl -X GET "https://developer-solution/fhir/4.0/Group/GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
PUT /fhir/4.0/Group/{id}
This method updates the Group resource matching the requested resource ID.
Name
Type
Data Type
Description
Name:
id
required
Type:
path
Data Type:
string
Description:
The ID of the Group resource.
Sample Value: GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ
Name:
Group
required
Type:
body
Data Type:
Description:
Contains the fields of the Group resource to be updated. The following fields must be present:
Group.id
Group.type
Group.actual
Note: The Group Resource Id shall match the FHIRID in the path. Updating a specific version is not supported.
Sample Payload:
{
"resourceType": "Group",
"id": "GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ",
"active": true,
"actual": true,
"type": "person",
"name": "my-group-name",
"member": [
{
"entity": {
"reference": "Patient/GYZGCNDDMRSWMQCPJBBVA"
}
},
{
"entity": {
"reference": "Patient/MYYDEOJSHAYTAQCPJBBVA"
}
}
]
}
200
The Group was updated. The Group FHIR ID is in the header.
400
This response code is returned when the query is invalid. e.g. Group.actual or Group.type are not defined.
401
This code is returned when the user is not authorised to perform the operation. In order to create or update groups the user should either be a member of the "FHIR Group Administrator" or the "FHIR Write Administrator" Group.
404
No Group resource found with the requested resource ID.
curl -X PUT "https://developer-solution/fhir/4.0/Group/GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-d '{"resourceType":"Group","id":"GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ","active":true,"actual":true,"type":"person","name":"my-group-name","member":[{"entity":{"reference":"Patient/GYZGCNDDMRSWMQCPJBBVA"}},{"entity":{"reference":"Patient/MYYDEOJSHAYTAQCPJBBVA"}}]}'
GET /fhir/4.0/Group/{id}/$export
This method exports the requested FHIR Bulk data for all the patients in the Group resource matching the requested Group resource ID. The export method is only supported for groups where all the members are patients. Only resources for active members of the group will be exported.
Name
Type
Data Type
Description
Name:
id
required
Type:
path
Data Type:
string
Description:
The ID of the Group resource.
Sample Value: GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ
Name:
_type
optional
Type:
query
Data Type:
array
Description:
Defines the resource type or types to be exported. If _type is not specified all available resources for the group members will be exported.
Sample Value: Patient,Immunization,Procedure
Name:
_since
optional
Type:
query
Data Type:
string
Description:
Filters the exported data to only include resources that have changed after the supplied time. Note: This only applies to the actual exported resource. The returned resources might contain references, or contain references that were updated before the specified _since instant.
Sample Value: 2022-01-31T23:59:59
Name:
_outputFormat
optional
Type:
query
Data Type:
string
Description:
Defines the format for the requested Bulk Data files to be generated. Only application/fhir+ndjson
is supported
Sample Value: application/fhir+ndjson
Name:
-include-sources
optional
Type:
query
Data Type:
array
Description:
The -include-sources parameter defines 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: The sources specified should be enabled.
Sample Value: Condition=Orion%20Health%E2%84%A2%20R4%20HL7V2%20Generic%20Problems,Orion%20Health%E2%84%A2%20R4%20HL7V2%20Encounter%20Diagnoses
Name:
-exclude-sources
optional
Type:
query
Data Type:
array
Description:
The -exclude-sources parameter defines 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 Value: Condition=Orion%20Health%E2%84%A2%20R4%20HL7V2%20Generic%20Problems,Orion%20Health%E2%84%A2%20R4%20HL7V2%20Encounter%20Diagnoses
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.
Default Value: application/fhir+json
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.
Default Value: respond-async
Sample Value: respond-async
202
The FHIR Bulk Export job was successfully triggered.
400
This code is returned in the following cases :
401
Not authorised to perform the operation.
404
No Group resource found with the requested resource ID.
429
The maximum of concurrent $export requests was reached. Currently only supports 5 concurrent requests.
curl -X GET "https://developer-solution/fhir/4.0/Group/GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ/$export?_type=Patient,Immunization,Procedure" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
POST /fhir/4.0/Group/{id}/$export
This method exports the requested FHIR Bulk data for all the patients in the Group resource matching the requested Group resource ID. Only resources for active members of the group will be exported.
Name
Type
Data Type
Description
Name:
id
required
Type:
path
Data Type:
string
Description:
The ID of the Group resource.
Sample Value: GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ
Name:
parameter
optional
Type:
body
Data Type:
Description:
Filters the export of Bulk data
parameter.name=_type
: Filters the export of Bulk data for the groups of specified type. This is a comma separated list of FHIR resource names.parameter.name=_since
: Filters the exported data to only include resources that have changed after the supplied time. parameter.name=_outputFormat
: Defines the format for the requested Bulk Data files to be generated. Only application/fhir+ndjson
is supportedparameter.name=patient
: Filters the exported data to only the specified patients. A repeatable parameter with Patient FHIR ID references. All specified patients should be active members of the group.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": "_type",
"valueString": "Patient, Immunization, Procedure"
}
]
}
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.
Default Value: application/fhir+json
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.
Default Value: respond-async
Sample Value: respond-async
202
The FHIR Bulk Export job was successfully triggered.
400
This code is returned in the following cases :
401
Not authorised to perform the operation.
404
No Group resource found with the requested resource ID.
429
The maximum of concurrent $export requests was reached. Currently only supports 5 concurrent requests.
curl -X POST "https://developer-solution/fhir/4.0/Group/GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ/$export" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-d '{"resourceType":"Parameters","parameter":[{"name":"_type","valueString":"Patient, Immunization, Procedure"}]}'
GET /fhir/4.0/Group/$export-poll-status
Obtain the status of a FHIR Bulk Group Export
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 job was not found.
405
The method is not allowed. Only GET is allowed.
500
The FHIR Bulk Export job failed due to internal errors.
curl -X GET "https://developer-solution/fhir/4.0/Group/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
DELETE /fhir/4.0/Group/$export-poll-status
Cancel an existing FHIR Bulk Group Export 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 Bulk not enabled.
401
The user is not authorised to perform the login. In order to cancel a FHIR Bulk Group export job the user should be a member of the 'FHIR Bulk Administrator' Group.
404
The FHIR Bulk export job was not found.
curl -X DELETE "https://developer-solution/fhir/4.0/Group/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='
GET /fhir/4.0/Group/$download
Download a file that was exported via a previous Bulk Group Export request.
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
Name:
resource
required
Type:
query
Data Type:
string
Description:
Filters the download content to the FHIR Resource type specified.
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 in the group can not be resolved or unauthorised access.
401
The user is not authorised for the operation.
404
The FHIR Bulk export job was not found.
405
The method is not allowed. Only GET is allowed.
500
The FHIR Bulk Export job failed unexpectedly.
curl -X GET "https://developer-solution/fhir/4.0/Group/$download?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff&file=Patient_1.ndjson" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='