FHIR Group

Base Path: /fhir/4.0/Group

Version: 2.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.
  • Retrieve the history of a Group resource based on its FHIR ID.
  • Retrieve a specific version of a Group resource based on its FHIR ID and Version 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 Group API aggregates data from multiple sources, to learn about working with aggregated APIs refer to the Working with Aggregation guide in the Knowledge Hub.

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/

Return all Group resources for the given search criteria, or all Group if a search criteria is not specified.

Parameters

Name

Type

Data Type

Description

Name:

actual

optional

Type:

query

Data Type:

string

Description:

Filters the groups by the descriptive or actual of the Group.

Note: Set the value to true to retrieve actual Groups or false to retrieve Descriptive Groups.


Sample Value: true

Name:

characteristic

optional

Type:

query

Data Type:

array

Description:

Filters the groups by the kind of characteristic. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: http://snomed.info/sct|90721000119105

Name:

characteristic-value

optional

Type:

query

Data Type:

array

Description:

Filters the groups by a value held by characteristic. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: http://snomed.info/sct|370134000

Name:

code

optional

Type:

query

Data Type:

array

Description:

Filters the groups by the kind of resources contained to ones that matches the specified code or codes. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: http://snomed.info/sct|73211009

Name:

exclude

optional

Type:

query

Data Type:

array

Description:

Filters the groups by the includes or excludes of group. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: sysA|true

Name:

identifier

optional

Type:

query

Data Type:

array

Description:

Filters groups by the identifier associated with the group.

Note: The identifier can be a single item or a comma separated list of identifiers. Each identifier is defined by system and value , separated using a URL encoded | character i.e. %7c.,


Sample Value: urn:oid:1.3.4.5.6.7|2345234234234, urn:text:sysA|2345

Name:

managing-entity

optional

Type:

query

Data Type:

array

Description:

Filters groups by the entity that is the custodian of the Group's definition, identified by their Group.managingEntity reference.

Note: managing-entity can be chained to define filters on the reference, each of the chained parameters can specify multiple comma separated values.


Sample Value: managing-entity:Practitioner.family=Smith&managing-entity:Practitioner.given=Bob,Robert

Name:

member

optional

Type:

query

Data Type:

array

Description:

Filters groups by the entity that is the reference to the group member, identified by their Group.member.entity reference.

Note: member can be chained to define filters on the reference, each of the chained parameters can specify multiple comma separated values.


Sample Value: member=OHCP|87228-5094&member:patient.gender=male

Name:

type

optional

Type:

query

Data Type:

array

Description:

Filters the groups to those that match the specified type. The type may consists of a coding system and a code separated using a URL encoded | character i.e. %7c The supported values are:

  • person
  • animal
  • practitioner
  • device
  • medication
  • substance

Note:


Sample Value: person

Name:

name

optional

Type:

query

Data Type:

array

Description:

Filters the groups to match with the specified name.

Note:

  • Supports passing in a comma-separated list of values.


Sample Value: smith-family

Name:

active

optional

Type:

query

Data Type:

string

Description:

Filters the groups by whether this group's record is in active use.

Note: Set the value to true to retrieve active Gorups or false to retrieve inactive Gorups.


Sample Value: true

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:

_summary

optional

Type:

query

Data Type:

string

Description:

Instructs the server to return a subset of the resource, reducing the size of the reponse payload. Possible values are

  • true: return summaries only
  • false: return full resources
  • count: return the count of search matches
  • text: return only the text, id, meta, and top-level mandatory elements
  • data: remove the text element


Sample Value: true

Name:

_lastUpdated

optional

Type:

query

Data Type:

array

Description:

Filters based on when the resource version was last changed, before, or after a specific date, date-time, or date range. The supported prefixes are gt, ge, lt, le and eq. If no prefix is used, exact date or date-time matching is implied. Dates must be formatted according to ISO 8601 either as a date only (e.g. 1997-07-16) or as a date-time including the timezone (e.g. 1997-07-16T19:20:30+13:00). Ensure that special characters such as + are URL encoded i.e. %2B.

The format of the query is

  • _lastUpdated=gt{dateTimeValue}
  • _lastUpdated=ge{dateTimeValue}&_lastUpdated=le{dateTimeValue}


Sample Value: ge2012-01-01T01:00:00+13:00

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=code,name,_elements:exclude=*.extension

Name:

-cursor

optional

Type:

query

Data Type:

string

Description:

A server internal parameter to navigate different pages.

This parameter is returned by the server as part of the Bundle 'next' link of a paginated query. And is used to retrieve the next page


Name:

_count

optional

Type:

query

Data Type:

integer

Description:

Limit the number of match results to the specified _count. When _count is specified, the query will be paginated, and only _count or less results will be returned.

The returned bundle may contain a next link if more results could be available.


Sample Value: 30

Name:

_sort

optional

Type:

query

Data Type:

array

Description:

Request which order results should be returned in.

Supported _sort parameters are:

  • active to sort by Group.active ascending
  • -active to sort by Group.active descending
  • actual to sort by Group.actual ascending
  • -actual to sort by Group.actual descending
  • name to sort by Group.name ascending
  • -name to sort by Group.name descending
  • _lastUpdated to sort by Group.Meta.lastUpdated ascending
  • -_lastUpdatedto sort by Group.Meta.lastUpdated descending

You can use any combination of the parameters


Default Value: -active

Sample Value: _sort=-active,_sort=-active, -_lastUpdated

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

Specifies the language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

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: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns a FHIR Bundle containing 0..* OperationOutcome resources and 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 by name and type
curl -X GET "https://developer-solution/fhir/4.0/Group?type=person&name=smith-family" \
-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:

object

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=' \
-H 'Content-Type: null' \
-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:

actual

optional

Type:

formData

Data Type:

string

Description:

Filters the groups by the descriptive or actual of the Group.

Note: Set the value to true to retrieve actual Groups or false to retrieve Descriptive Groups.


Sample Value: true

Name:

characteristic

optional

Type:

formData

Data Type:

array

Description:

Filters the groups by the kind of characteristic. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: http://snomed.info/sct|90721000119105

Name:

characteristic-value

optional

Type:

formData

Data Type:

array

Description:

Filters the groups by a value held by characteristic. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: http://snomed.info/sct|370134000

Name:

code

optional

Type:

formData

Data Type:

array

Description:

Filters the groups by the kind of resources contained to ones that matches the specified code or codes. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: http://snomed.info/sct|73211009

Name:

exclude

optional

Type:

formData

Data Type:

array

Description:

Filters the groups by the includes or excludes of group. The code value consists of a coding system and a code separated using a URL encoded | character i.e. %7c

Note: Supports passing in a comma-separated list of values


Sample Value: sysA|true

Name:

identifier

optional

Type:

formData

Data Type:

array

Description:

Filters groups by the identifier associated with the group.

Note: The identifier can be a single item or a comma separated list of identifiers. Each identifier is defined by system and value , separated using a URL encoded | character i.e. %7c.,


Sample Value: urn:oid:1.3.4.5.6.7|2345234234234, urn:text:sysA|2345

Name:

managing-entity

optional

Type:

formData

Data Type:

array

Description:

Filters groups by the entity that is the custodian of the Group's definition, identified by their Group.managingEntity reference.

Note: managing-entity can be chained to define filters on the reference, each of the chained parameters can specify multiple comma separated values.


Sample Value: managing-entity:Practitioner.family=Smith&managing-entity:Practitioner.given=Bob,Robert

Name:

member

optional

Type:

formData

Data Type:

array

Description:

Filters groups by the entity that is the reference to the group member, identified by their Group.member.entity reference.

Note: member can be chained to define filters on the reference, each of the chained parameters can specify multiple comma separated values.


Sample Value: member=OHCP|87228-5094&member:patient.gender=male

Name:

type

optional

Type:

formData

Data Type:

array

Description:

Filters the groups to those that match the specified type. The type may consists of a coding system and a code separated using a URL encoded | character i.e. %7c The supported values are:

  • person
  • animal
  • practitioner
  • device
  • medication
  • substance

Note:


Sample Value: person

Name:

name

optional

Type:

formData

Data Type:

array

Description:

Filters the groups to match with the specified name.

Note:

  • Supports passing in a comma-separated list of values.


Sample Value: smith-family

Name:

active

optional

Type:

formData

Data Type:

string

Description:

Filters the groups by whether this group's record is in active use.

Note: Set the value to true to retrieve active Gorups or false to retrieve inactive Gorups.


Sample Value: true

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:

_summary

optional

Type:

formData

Data Type:

string

Description:

Instructs the server to return a subset of the resource, reducing the size of the reponse payload. Possible values are

  • true: return summaries only
  • false: return full resources
  • count: return the count of search matches
  • text: return only the text, id, meta, and top-level mandatory elements
  • data: remove the text element


Sample Value: true

Name:

_lastUpdated

optional

Type:

formData

Data Type:

array

Description:

Filters based on when the resource version was last changed, before, or after a specific date, date-time, or date range. The supported prefixes are gt, ge, lt, le and eq. If no prefix is used, exact date or date-time matching is implied. Dates must be formatted according to ISO 8601 either as a date only (e.g. 1997-07-16) or as a date-time including the timezone (e.g. 1997-07-16T19:20:30+13:00). Ensure that special characters such as + are URL encoded i.e. %2B.

The format of the query is

  • _lastUpdated=gt{dateTimeValue}
  • _lastUpdated=ge{dateTimeValue}&_lastUpdated=le{dateTimeValue}


Sample Value: ge2012-01-01T01:00:00+13:00

Name:

_elements

optional

Type:

formData

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=code,name,_elements:exclude=*.extension

Name:

-cursor

optional

Type:

formData

Data Type:

string

Description:

A server internal parameter to navigate different pages.

This parameter is returned by the server as part of the Bundle 'next' link of a paginated query. And is used to retrieve the next page


Name:

_count

optional

Type:

formData

Data Type:

integer

Description:

Limit the number of match results to the specified _count. When _count is specified, the query will be paginated, and only _count or less results will be returned.

The returned bundle may contain a next link if more results could be available.


Sample Value: 30

Name:

_sort

optional

Type:

formData

Data Type:

array

Description:

Request which order results should be returned in.

Supported _sort parameters are:

  • active to sort by Group.active ascending
  • -active to sort by Group.active descending
  • actual to sort by Group.actual ascending
  • -actual to sort by Group.actual descending
  • name to sort by Group.name ascending
  • -name to sort by Group.name descending
  • _lastUpdated to sort by Group.Meta.lastUpdated ascending
  • -_lastUpdatedto sort by Group.Meta.lastUpdated descending

You can use any combination of the parameters


Default Value: -active

Sample Value: _sort=-active,_sort=-active, -_lastUpdated

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

Specifies the language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

_format

optional

Type:

formData

Data Type:

string

Description:

Media type of the response. It takes precedence over the Accept header. Possible values are json and xml.


Default Value: json

Sample Value: json

Name:

_pretty

optional

Type:

formData

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


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=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:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

The language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=name,code,_elements:exclude=*.extension

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: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns an Group resource matching the requested resource ID.

application/json+fhir

400

This code is returned when the resource ID is empty or not valid.

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:

object

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=' \
-H 'Content-Type: null' \
-d '{"resourceType":"Group","id":"GVAE64TJN5XCASDFMFWHI2HCQSRCAURUEBDXE33VOAQFG5DPOJSQ","active":true,"actual":true,"type":"person","name":"my-group-name","member":[{"entity":{"reference":"Patient/GYZGCNDDMRSWMQCPJBBVA"}},{"entity":{"reference":"Patient/MYYDEOJSHAYTAQCPJBBVA"}}]}'

Retrieve a Group's history

GET /fhir/4.0/Group/{id}/_history

This method returns the change history for an Group resource matching the requested resource ID. Group resources can be retrieved from multiple data sources, and not all sources are able to return history information. This operation will return an empty set of data if no versions of the specified Group can be found, which includes cases where:

  • The specified Group resource cannot be found.
  • The data source for the Group is unable to return history information.

Parameters

Name

Type

Data Type

Description

Name:

id

required

Type:

path

Data Type:

string

Description:

The ID of the Group resource.


Sample Value: shaGGV557CI4XDVXL4AI3QWZG73JQZC7ERLR2TSVLJ4NDO55CNSSZ5A

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

The language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=code,name,_elements:exclude=*.extension

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: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns a Group resource matching the requested resource ID.

application/json+fhir

400

  • The source providing the Group resource is not capable of returning history of Group resources.

application/json+fhir

404

  • No Group resource found with the requested resource ID.

Sample Requests

Retrieve the history of a Group with a specific resource id
curl -X GET "https://developer-solution/fhir/4.0/Group/shaGGV557CI4XDVXL4AI3QWZG73JQZC7ERLR2TSVLJ4NDO55CNSSZ5A/_history" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

Retrieve a specific version of a Group

GET /fhir/4.0/Group/{id}/_history/{versionid}

This method returns a specific version of the Group resource matching the requested resource ID. Group resources can be retrieved from multiple data sources. This operation will return an empty set of data if no versions of the specified Group can be found, which includes cases where:

  • The specified Group resource cannot be found.

Parameters

Name

Type

Data Type

Description

Name:

id

required

Type:

path

Data Type:

string

Description:

The ID of the Group resource.


Sample Value: shaGGV557CI4XDVXL4AI3QWZG73JQZC7ERLR2TSVLJ4NDO55CNSSZ5A

Name:

versionid

required

Type:

path

Data Type:

string

Description:

The version of the Group resource


Sample Value: 1

Name:

Accept-Language

optional

Type:

header

Data Type:

string

Description:

The language that the results will be translated to. If not specified it will default to the server's locale. (e.g. fr-FR for french)


Sample Value: en-US

Name:

X-Request-Id

optional

Type:

header

Data Type:

string

Description:

Supply a request Id to track the request.


Sample Value: adUEctf6urd

Name:

_elements

optional

Type:

query

Data Type:

array

Description:

Request a specific set of elements be returned, or excluded as part of a resource in the search results. Use _elements for the elements to include and _elements:exclude for the elements to exclude.


Sample Value: _elements=name,code,_elements:exclude=*.extension

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: json

Sample Value: json

Name:

_pretty

optional

Type:

query

Data Type:

string

Description:

Ask for a pretty printed response for human convenience.


Default Value: true

Sample Value: true

Name:

Accept

optional

Type:

header

Data Type:

string

Description:

Media type of the response. Possible values are application/json and application/xml. If both _format and Accept are specified, _format takes precedence.


Default Value: application/json

Sample Value: application/json

Name:

CSRF-Token

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. The csrfToken from the OHP session must be included in this header.

System will validate the token and reject the request if the token is invalid or not present.

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Name:

X-Send-Open-API

required

Type:

header

Data Type:

string

Description:

This header is required for CSRF protection. This header is required to distinguish the api requests from known senders.

System will validate "X-Send-Open-API" request header is present or not. If it is not present, system will reject the request

Note: Either CSRF-Token or X-Send-Open-API must be included in headers to do the CSRF protection.


Responses

application/json+fhir

200

Returns a Group resource matching the the requested resource ID and version id.

application/json+fhir

400

The source providing the Group resource is not capable of returning history of Group resources.

application/json+fhir

404

  • No Group resource found with the requested resource ID.
  • The version id specified does not exist for the Group resource with the requested resource ID.

Sample Requests

Retrieve the version of Group identified by a resource id and a version id
curl -X GET "https://developer-solution/fhir/4.0/Group/shaGGV557CI4XDVXL4AI3QWZG73JQZC7ERLR2TSVLJ4NDO55CNSSZ5A/_history/1" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='

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: 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/$expor?_type=Patient,Immunization,Procedure" \
-H 'Accept: application/json' \
-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:

object

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 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8=' \
-H 'Content-Type: null' \
-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-statu?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Accept: application/json' \
-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-statu?jobid=7fc54d79-2701-417b-a790-0e9a739d37ff" \
-H 'Accept: application/json' \
-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:

id

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/$downloa?file=Patient_1.ndjson" \
-H 'Accept: application/json' \
-H 'Authorization: Basic bGV2ZWwxLnN5c19hOk9yaW9uc3k1IT8='