Group

Group is a FHIR resource that represents a collection of entities such as people, medications, or devices. In the context of Flexpa API, Group resources are automatically created during data synchronization to provide a convenient way to reference all patients retrieved in a sync job.

When Flexpa API processes a sync job, it automatically creates a Group resource containing references to all Patient resources retrieved during that operation. This provides an organizational structure that links a patient authorization to the complete set of patients retrieved.

The Group resource ID is set to match the patient authorization ID, creating a direct 1:1 relationship between the authorization and the group of patients it represents. This makes it easy to query for all patients associated with a specific authorization.

FHIR API

https://api.flexpa.com/fhir/Group

New to FHIR?

Intro to FHIR

FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically

Read introduction →

#Schema

#Overview

The FHIR R4 Group resource represents a collection of entities. As a FHIR resource, it follows standard FHIR patterns with common elements like resourceType, id, meta, and identifier.

Flexpa API automatically creates Group resources during sync operations to organize Patient resources. These groups are always of type person and represent actual collections (not definitions), indicated by the actual field being set to true.

The Group resource serves as an organizational tool that connects a patient authorization to all patients retrieved during the associated sync job. Because the Group ID matches the patient authorization ID, you can easily retrieve all patients for a specific authorization.

Group resources are created automatically during sync jobs and do not need to be explicitly requested. They will be included in the bundle of resources returned by sync operations.

Elements

idid: The unique identifier for the Group resource. For Flexpa-generated groups, this matches the patient authorization ID, creating a 1:1 relationship between the authorization and the group.
metaMeta: Metadata about the resource. See also Tags defined by Flexpa.
lastUpdatedinstant: The last time the group was updated
typecode: The type of entities in the group; Codes
person
Group contains Person or Patient resources (used by Flexpa)
animal
Group contains Animal resources
practitioner
Group contains Practitioner resources
device
Group contains Device resources
medication
Group contains Medication resources
substance
Group contains Substance resources
actualboolean: Whether this group represents an actual collection of entities or a definition. For Flexpa-generated groups, this is always true, indicating the group represents actual Patient resources that were retrieved.
memberarray: The entities that are members of this group
entityReference(Patient|Practitioner|Device|Medication|Substance): Reference to the entity that is a member of the group. For Flexpa-generated groups, these are always Patient references in the format Patient/[id].

Group Example

{
  "resourceType": "Group",
  "id": "f1903dfc-1d2f-45ba-bf24-05cc2b062182",
  "type": "person",
  "actual": true,
  "member": [
    {
      "entity": {
        "reference": "Patient/19fbd276-1690-5c51-bae2-ad4ae52c97e4"
      }
    },
    {
      "entity": {
        "reference": "Patient/e8abda93-50e9-5c8e-a6f6-8921f544e45e"
      }
    }
  ]
}

#API

GEThttps://api.flexpa.com/fhir/Group/:id

#Read

A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.

For Flexpa-generated Group resources, the Group ID matches the patient authorization ID. This means you can retrieve the group of all patients associated with a specific authorization by using the authorization ID as the Group ID.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token or an Application Access Token

Request path parameters

idstring: The identifier of the Group resource to retrieve. For Flexpa-generated groups, this is the patient authorization ID.

Request

GET

/fhir/Group/:id

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Group/[authorization-id] \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "resourceType": "Group",
  "id": "f1903dfc-1d2f-45ba-bf24-05cc2b062182",
  "type": "person",
  "actual": true,
  "member": [
    {
      "entity": {
        "reference": "Patient/19fbd276-1690-5c51-bae2-ad4ae52c97e4"
      }
    }
  ]
}

GEThttps://api.flexpa.com/fhir/Group

#Search

Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token or an Application Access Token

Search parameters

memberreference: Reference to an entity (typically a Patient) that is a member of the group
typetoken: The type of resources the group contains (for Flexpa-generated groups, this is person)
actualtoken: Whether the group represents an actual group of entities (for Flexpa-generated groups, this is true)
_idtoken: The logical resource ID. For Flexpa-generated groups, this matches the patient authorization ID.

Request

GET

/fhir/Group

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Group \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Group",
        "id": "f1903dfc-1d2f-45ba-bf24-05cc2b062182",
        "type": "person",
        "actual": true,
        "member": [
          {
            "entity": {
              "reference": "Patient/19fbd276-1690-5c51-bae2-ad4ae52c97e4"
            }
          }
        ]
      }
    }
  ]
}

POSThttps://api.flexpa.com/fhir/Group/$expunge

#$expunge

The $expunge operation permanently deletes all Patient resources and associated clinical data for a consent. This operation is used when a patient revokes their consent or when data needs to be removed from the system.

When called, this operation expunges all Patient resources associated with the consent along with all their associated clinical data. The deletion runs asynchronously: the operation returns a 202 with an array of OperationOutcome resources confirming that the expunge has been scheduled.

The $expunge operation is permanent and cannot be undone. All Patient resources and their associated clinical data will be permanently deleted from the Flexpa API system.

Request headers

Authorizationstring: An Authorization: Bearer header value must be presented with a Patient Access Token

Response

OperationOutcome[]array: The response is an array of FHIR OperationOutcome resources, one per patient authorization in the consent. Each has a single issue with severity information confirming that the expunge for that authorization has been scheduled.

Request

POST

/fhir/Group/$expunge

ACCESS_TOKEN=flexpa-link-access-token

curl -X POST https://api.flexpa.com/fhir/Group/\$expunge \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response (202 Accepted)

[
  {
    "resourceType": "OperationOutcome",
    "issue": [
      {
        "severity": "information",
        "code": "informational",
        "diagnostics": "Expunge scheduled for authorization f1903dfc-1d2f-45ba-bf24-05cc2b062182 (expunge-consent-0b2a5c5e-7d3e-4d1a-9f2b-6c8e1d4a7b3f)"
      }
    ]
  },
  {
    "resourceType": "OperationOutcome",
    "issue": [
      {
        "severity": "information",
        "code": "informational",
        "diagnostics": "Expunge scheduled for authorization 9a4c1e77-3b2d-4f60-8e15-2d7c5b9a1f04 (expunge-consent-0b2a5c5e-7d3e-4d1a-9f2b-6c8e1d4a7b3f)"
      }
    ]
  }
]