Group

Overview

The Group resource represents a defined collection of entities that may be discussed or acted upon collectively but are not expected to act collectively, and are not formally or legally recognized. Groups are used to organize patients, practitioners, or other resources for administrative or clinical purposes.

Key Use Cases:

• Organizing patients by condition, treatment protocol, or care program
• Managing cohorts for clinical studies or quality measures
• Grouping members for insurance coverage or benefits administration
• Supporting population health management initiatives

Relationships to Other Resources:

• Patient - Individual members of the group
• Practitioner - Healthcare providers associated with the group
• Organization - Organizations that manage or sponsor the group
• Coverage - Insurance coverage associated with group members

Resource Schema

Key fields in the Group resource:

{
  "resourceType": "Group",
  "id": "string",
  "identifier": [
    {
      "system": "http://example.org/group-id",
      "value": "group-123"
    }
  ],
  "active": true,
  "type": "person|animal|practitioner|device|medication|substance",
  "code": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/group-type",
        "code": "person",
        "display": "Person"
      }
    ]
  },
  "quantity": 0,
  "managingEntity": {
    "reference": "Organization/org-123"
  },
  "characteristic": [
    {
      "code": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/characteristic-code",
            "code": "gender",
            "display": "Gender"
          }
        ]
      },
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/administrative-gender",
            "code": "female",
            "display": "Female"
          }
        ]
      },
      "exclude": false
    }
  ],
  "member": [
    {
      "entity": {
        "reference": "Patient/patient-123"
      },
      "period": {
        "start": "2023-01-01",
        "end": "2023-12-31"
      },
      "inactive": false
    }
  ]
}

Key Fields:

• id - Unique identifier for the group
• type - Type of entities in the group (person, practitioner, etc.)
• code - Classification or type of group
• member - Individual members of the group

Operations

Read

Retrieve a specific group by ID.

Production

GET /Group/{id}

Example Request

curl -X GET https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/group-123 \
    -H "Accept: application/fhir+json"

Preview

GET /Group/{id}

Example Request

curl -X GET https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/group-123 \
    -H "Accept: application/fhir+json"

Search

Search for groups using various criteria.

Production

GET /Group?parameter=value
POST /Group/_search

Preview

GET /Group?parameter=value
POST /Group/_search

Search Parameters

Search Parameters:

Parameter	Type	Required	Description	Example
code	token	No	Group classification code	code=diabetes-patients
member	reference	No	Reference to group member	member=Patient/patient-123
type	token	No	Type of group (person, practitioner, etc.)	type=person

Common Search Patterns

Find groups by member:

GET /Group?member=Patient/patient-123&_count=10

Search by group type:

GET /Group?type=person

Find by group code:

GET /Group?code=diabetes-management

Search with reverse includes:

GET /Group?type=person&_revinclude=Coverage:beneficiary

Examples

Request Examples

Production

Search by member

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "member=Patient/patient-123&_count=10"

Search by type

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=person"

Search by code

curl -X POST https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "code=diabetes-management"

Preview

Search by member

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "member=Patient/patient-123&_count=10"

Search by type

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "type=person"

Search by code

curl -X POST https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/Group/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "code=diabetes-management"

Response Examples

Successful Search Response

Group Search Bundle

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Group",
        "id": "diabetes-care-group",
        "identifier": [
          {
            "system": "http://example.org/group-id",
            "value": "DCG-2023-001"
          }
        ],
        "active": true,
        "type": "person",
        "code": {
          "coding": [
            {
              "system": "http://example.org/group-codes",
              "code": "diabetes-management",
              "display": "Diabetes Management Program"
            }
          ]
        },
        "quantity": 25,
        "managingEntity": {
          "reference": "Organization/netsmart-health"
        },
        "characteristic": [
          {
            "code": {
              "coding": [
                {
                  "system": "http://snomed.info/sct",
                  "code": "44054006",
                  "display": "Diabetes mellitus type 2"
                }
              ]
            },
            "valueBoolean": true,
            "exclude": false
          }
        ],
        "member": [
          {
            "entity": {
              "reference": "Patient/patient-123"
            },
            "period": {
              "start": "2023-01-01"
            },
            "inactive": false
          },
          {
            "entity": {
              "reference": "Patient/patient-456"
            },
            "period": {
              "start": "2023-02-15"
            },
            "inactive": false
          }
        ]
      }
    }
  ]
}

Individual Group Response

Single Group Resource

{
  "resourceType": "Group",
  "id": "hypertension-cohort",
  "identifier": [
    {
      "system": "http://example.org/group-id",
      "value": "HTN-2023-002"
    }
  ],
  "active": true,
  "type": "person",
  "code": {
    "coding": [
      {
        "system": "http://example.org/group-codes",
        "code": "hypertension-monitoring",
        "display": "Hypertension Monitoring Program"
      }
    ]
  },
  "quantity": 42,
  "managingEntity": {
    "reference": "Organization/netsmart-health"
  },
  "characteristic": [
    {
      "code": {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "38341003",
            "display": "Hypertensive disorder"
          }
        ]
      },
      "valueBoolean": true,
      "exclude": false
    },
    {
      "code": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v3-AdministrativeGender",
            "code": "gender",
            "display": "Gender"
          }
        ]
      },
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/administrative-gender",
            "code": "female",
            "display": "Female"
          }
        ]
      },
      "exclude": false
    }
  ],
  "member": [
    {
      "entity": {
        "reference": "Patient/patient-789"
      },
      "period": {
        "start": "2023-03-01"
      },
      "inactive": false
    }
  ]
}

Empty Result Set

No Groups Found

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}

Integration Patterns

Common Workflows

1. Patient Group Membership Lookup

# Step 1: Find groups containing a specific patient
GET /Group?member=Patient/patient-123

# Step 2: Get detailed group information
GET /Group/diabetes-care-group

# Step 3: Find other members of the same group
GET /Patient?_has:Group:member:_id=diabetes-care-group

2. Population Health Management

# Step 1: Find all diabetes management groups
GET /Group?code=diabetes-management

# Step 2: Get group members for outreach
GET /Group/diabetes-care-group

# Step 3: Find related coverage information
GET /Coverage?beneficiary=Patient/patient-123

Related Resources

• Patient - Individual members of the group
• Practitioner - Healthcare providers associated with the group
• Organization - Organizations that manage or sponsor the group
• Coverage - Insurance coverage associated with group members

Include Parameters

Use _include and _revinclude to fetch related resources:

# Get group with member patient details
GET /Group?code=diabetes-management&_include=Group:member

# Get groups with related coverage information
GET /Group?type=person&_revinclude=Coverage:beneficiary

Error Handling

The Group resource follows standard FHIR error handling patterns. For detailed error responses and troubleshooting guidance, see the Common Errors page.

Group-Specific Error Scenarios

• 404 Not Found: Group ID doesn't exist or group is inactive
• 400 Bad Request: Invalid search parameters or malformed member references
• Empty Results: No groups match the search criteria

Troubleshooting Tips

• No Results for Member Search: Verify patient reference format and ensure patient exists
• Type Parameter Issues: Ensure type values match supported group types (person, practitioner, etc.)
• Code Search Problems: Verify group code systems and values are correct
• Performance Issues: Use _count parameter to limit result sets for large groups

Supported Profiles

• HL7 FHIR R4 Group
• US Core Group