FHIR Group

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:

  • Retrieve all Group resources that match a search criteria.
  • Retrieve a specific Group resource based on its resource ID
  • Create a Group.
  • Update an existing Group resource based on its resource ID.
  • Export a subset or all available or requested data for the group members based on the Group resource ID
  • 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.

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.

Methods

Retrieve Groups

GET /fhir/4.0/Group/

This method returns all available Group resources. Optionally filtering by search criterias.

Parameters

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

Responses

application/json+fhir

200

Returns a FHIR Bundle containing 0..* Group resources.

application/json+fhir

400

This response code is returned when the query is invalid e.g. an invalid parameter or a partial token in the search.

Sample Requests

Retrieve all groups matching specified criteria
curl -X GET "https://developer-solution/fhir/4.0/Group/?member=Patient/GYZGCNDDMRSWMQCPJBBVA&type=person" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Create a Group

POST /fhir/4.0/Group/

This method creates a Group.

Parameters

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"
      }
    }
  ]
}


Responses

application/json+fhir

201

This response code is returned when a new Group is created successfully. The Group FHIR Id is in the header.

application/json+fhir

400

This response code is returned when the query is invalid. e.g. Group.actual or Group.type are not defined.

application/json+fhir

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.

Sample Requests

Create a group with specified resource fields
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"}}]}'

Retrieve Groups

POST /fhir/4.0/Group/_search

This method returns all available groups. Optionally filtering by the specified search criteria.

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:

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

Responses

application/json+fhir

200

Returns a FHIR Bundle containing 0..* Group resources.

application/json+fhir

400

This response code is returned when the query is invalid e.g. an invalid parameter or a partial token in the search.

Sample Requests

Get all Groups with specified name
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'

Retrieve a single Group

GET /fhir/4.0/Group/{id}

This method returns the Group resource matching the requested resource ID.

Parameters

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

Responses

application/json+fhir

200

Returns an Group resource matching the requested resource ID.

application/json+fhir

404

No Group resource found with the requested resource ID.

Sample Requests

Retrieve group with a specified resource ID
curl -X GET "https://developer-solution/fhir/4.0/Group/GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Updates a Group

PUT /fhir/4.0/Group/{id}

This method updates the Group resource matching the requested resource ID.

Parameters

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"
      }
    }
  ]
}


Responses

application/json+fhir

200

The Group was updated. The Group FHIR ID is in the header.

application/json+fhir

400

This response code is returned when the query is invalid. e.g. Group.actual or Group.type are not defined.

application/json+fhir

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.

application/json+fhir

404

No Group resource found with the requested resource ID.

Sample Requests

Update an existing group with a specified 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"}}]}'

Bulk Export for a group

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.

Parameters

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

Responses

application/json+fhir

202

The FHIR Bulk Export job was successfully triggered.

application/json+fhir

400

This code 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
  • Invalid query parameter was requested
  • The Group requested for export is NOT of Group.type=person
  • The Group to be exported doesn't contain any active members
  • One or more Group members are defined more than once in the Group
  • The selected Group for export is too big (currently export is supported only for groups with 20 or less patients)
  • One or more patients in the group are not known or cannot be resolved
  • The user doesn't have FULL ACCESS to ALL the patients in the Group to be exported.

application/json+fhir

401

Not authorised to perform the operation.

application/json+fhir

404

No Group resource found with the requested resource ID.

application/json+fhir

429

The maximum of concurrent $export requests was reached. Currently only supports 5 concurrent requests.

Sample Requests

Export FHIR Bulk data for all patients in a Group identified by a specific ID.
curl -X GET "https://developer-solution/fhir/4.0/Group/GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ/$export?_type=Patient,Immunization,Procedure" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Bulk Export for a group

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.

Parameters

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 supported
  • parameter.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

Responses

application/json+fhir

202

The FHIR Bulk Export job was successfully triggered.

application/json+fhir

400

This code 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
  • Invalid query parameter was requested
  • The Group requested for export is NOT of Group.type=person
  • The Group to be exported doesn't contain any active members
  • One or more Group members are defined more than once in the Group
  • The selected Group for export is too big (currently export is supported only for groups with 20 or less patients)
  • One or more patients in the group are not known or cannot be resolved
  • The user doesn't have FULL ACCESS to ALL the patients in the Group to be exported

application/json+fhir

401

Not authorised to perform the operation.

application/json+fhir

404

No Group resource found with the requested resource ID.

application/json+fhir

429

The maximum of concurrent $export requests was reached. Currently only supports 5 concurrent requests.

Sample Requests

Export patient data of a group with a specified resource ID
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"}]}'

Retrieve Group Export job status

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

Obtain the status of a FHIR Bulk Group Export

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 job was not found.

application/json+fhir

405

The method is not allowed. Only GET is allowed.

application/json+fhir

500

The FHIR Bulk Export job failed due to internal errors.

Sample Requests

Retrieve the status of an export job with specified ID
curl -X GET "https://developer-solution/fhir/4.0/Group/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Cancel a Group Export job

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

Cancel an existing FHIR Bulk Group Export 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 Bulk not enabled.

application/json+fhir

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.

application/json+fhir

404

The FHIR Bulk export job was not found.

Sample Requests

Cancel an export job specified by an ID.
curl -X DELETE "https://developer-solution/fhir/4.0/Group/$export-poll-status?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Download exported file

GET /fhir/4.0/Group/$download

Download a file that was exported via a previous Bulk Group Export request.

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

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

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 in the group can not be resolved or unauthorised access.

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

The method is not allowed. Only GET is allowed.

application/json+fhir

500

The FHIR Bulk Export job failed unexpectedly.

Sample Requests

Download a file that contains resources exported by a specific job id.
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='