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
Preview

GET /Group/{id}

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

GET /Group/{id}

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

Search

Search for groups using various criteria.

GET Method

Use GET for simple searches with parameters in the query string.

Production
Preview

GET /Group?parameter=value

GET /Group?parameter=value

POST Method

Use POST for complex searches with form-encoded parameters.

Production
Preview

POST /Group/_search

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

Export ($export)

Initiate a bulk data export for all members of a specific group. This operation supports the FHIR Bulk Data Access Implementation Guide for asynchronous export of large datasets.

GET Method

Use GET for simple exports with parameters in the query string.

Production
Preview

GET /Group/{id}/$export

Example Request
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export?_type=Patient,Observation \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

GET /Group/{id}/$export

Example Request
curl -X GET https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export?_type=Patient,Observation \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

POST Method

Use POST for complex exports with parameters in a FHIR Parameters resource.

Production
Preview

POST /Group/{id}/$export

Example Request
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/fhir+json" \
    -d '{
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "_type",
          "valueString": "Patient,Observation,Condition"
        },
        {
          "name": "_since",
          "valueInstant": "2023-01-01T00:00:00Z"
        },
        {
          "name": "_outputFormat",
          "valueString": "application/fhir+ndjson"
        }
      ]
    }'

POST /Group/{id}/$export

Example Request
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/fhir+json" \
    -d '{
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "_type",
          "valueString": "Patient,Observation,Condition"
        },
        {
          "name": "_since",
          "valueInstant": "2023-01-01T00:00:00Z"
        },
        {
          "name": "_outputFormat",
          "valueString": "application/fhir+ndjson"
        }
      ]
    }'

Export Parameters

Parameter	Type	Description	Example
`_type`	string	Comma-separated list of resource types to export	`Patient,Observation,Condition`
`_since`	instant	Only export resources modified since this date	`2023-01-01T00:00:00Z`
`_outputFormat`	string	Format for exported files	`application/fhir+ndjson`, `ndjson`, `application/ndjson`

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

Export ($export)

Initiate a bulk data export for all members of a specific group. This operation supports the FHIR Bulk Data Access Implementation Guide for asynchronous export of large datasets.

GET Method

Use GET for simple exports with parameters in the query string.

Production
Preview

GET /Group/{id}/$export

Example Request
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export?_type=Patient,Observation \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

GET /Group/{id}/$export

Example Request
curl -X GET https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export?_type=Patient,Observation \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

POST Method

Use POST for complex exports with parameters in a FHIR Parameters resource.

Production
Preview

POST /Group/{id}/$export

Example Request
curl -X POST https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/fhir+json" \
    -d '{
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "_type",
          "valueString": "Patient,Observation,Condition"
        },
        {
          "name": "_since",
          "valueInstant": "2023-01-01T00:00:00Z"
        },
        {
          "name": "_outputFormat",
          "valueString": "application/fhir+ndjson"
        }
      ]
    }'

POST /Group/{id}/$export

Example Request
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/fhir+json" \
    -d '{
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "_type",
          "valueString": "Patient,Observation,Condition"
        },
        {
          "name": "_since",
          "valueInstant": "2023-01-01T00:00:00Z"
        },
        {
          "name": "_outputFormat",
          "valueString": "application/fhir+ndjson"
        }
      ]
    }'

Export Parameters

Parameter	Type	Description	Example
`_type`	string	Comma-separated list of resource types to export	`Patient,Observation,Condition`
`_since`	instant	Only export resources modified since this date	`2023-01-01T00:00:00Z`
`_outputFormat`	string	Format for exported files	`application/fhir+ndjson`, `ndjson`, `application/ndjson`

Export Response

Initial Response (202 Accepted):

HTTP/1.1 202 Accepted
Content-Location: https://fhir.netsmartcloud.com/provider/export-status/v2/{tenant-id}/jobs/550e8400-e29b-41d4-a716-446655440000

Status Check Response (In Progress):

HTTP/1.1 202 Accepted
X-Progress: Running (45% complete)
Retry-After: 120

Completion Response (200 OK):

{
  "transactionTime": "2024-01-15T10:30:00Z",
  "request": "https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "Patient",
      "url": "https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Binary/export-550e8400-e29b-41d4-a716-446655440000-Patient-1/$export-download"
    },
    {
      "type": "Observation",
      "url": "https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Binary/export-550e8400-e29b-41d4-a716-446655440000-Observation-2/$export-download"
    }
  ],
  "error": [
    {
      "type": "OperationOutcome",
      "url": "https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Binary/export-550e8400-e29b-41d4-a716-446655440000-OperationOutcome-1/$export-download"
    }
  ]
}

For more details, see the FHIR Bulk Data Access IG Group Export Operation.

Notes:

Export operations are asynchronous and may take several minutes to complete
Use the Content-Location header to poll for export status
Monitor the X-Progress header for completion status
Download files using the Binary $export-download operation

Integration Patterns

Complete Bulk Export Workflow

Production
Preview

1. Initiate Export
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export?_type=Patient,Observation \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

2. Check Export Status (repeat until complete)
curl -X GET https://fhir.netsmartcloud.com/provider/export-status/v2/{tenant-id}/jobs/550e8400-e29b-41d4-a716-446655440000 \
    -H "Accept: application/fhir+json"

3. Download Export Files
curl -X GET https://fhir.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Binary/export-550e8400-e29b-41d4-a716-446655440000-Patient-1/$export-download \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+ndjson"

1. Initiate Export
curl -X GET https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Group/group-123/$export?_type=Patient,Observation \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async"

2. Check Export Status (repeat until complete)
curl -X GET https://fhirtest.netsmartcloud.com/provider/export-status/v2/{tenant-id}/jobs/550e8400-e29b-41d4-a716-446655440000 \
    -H "Accept: application/fhir+json"

3. Download Export Files
curl -X GET https://fhirtest.netsmartcloud.com/provider/system-access/v2/{tenant-id}/Binary/export-550e8400-e29b-41d4-a716-446655440000-Patient-1/$export-download \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/fhir+ndjson"

Binary - Download exported data files using $export-download
Patient - Individual members included in group exports
Observation - Clinical data exported for group members
Condition - Diagnosis information for group members header for completion percentage

Recommendations

Use the Retry-After header to determine optimal polling intervals
Exported files are in NDJSON format (newline-delimited JSON)
Access tokens are required to download exported files

Examples

Request Examples

Production
Preview

Search by member
curl -X POST https://fhir.netsmartcloud.com/provider/system-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/system-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/system-access/v2/{tenant-id}/Group/_search \
    -H "Accept: application/fhir+json" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "code=diabetes-management"

Search by member
curl -X POST https://fhirtest.netsmartcloud.com/provider/system-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/system-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/system-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

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

Overview​

Resource Schema​

Operations​

Read​

Search​

GET Method​

POST Method​

Search Parameters​

Common Search Patterns​

Export ($export)​

GET Method​

POST Method​

Export Parameters​

Common Search Patterns​

Export ($export)​

GET Method​

POST Method​

Export Parameters​

Export Response​

Integration Patterns​

Complete Bulk Export Workflow​

Related Resources​

Recommendations​

Examples​

Request Examples​

Response Examples​

Successful Search Response​

Individual Group Response​

Empty Result Set​

Integration Patterns​

Common Workflows​

Related Resources​

Include Parameters​

Error Handling​

Group-Specific Error Scenarios​

Troubleshooting Tips​

Supported Profiles​

Overview

Resource Schema

Operations

Read

Search

GET Method

POST Method

Search Parameters

Common Search Patterns

Export ($export)

GET Method

POST Method

Export Parameters

Common Search Patterns

Export ($export)

GET Method

POST Method

Export Parameters

Export Response

Integration Patterns

Complete Bulk Export Workflow

Related Resources

Recommendations

Examples

Request Examples

Response Examples

Successful Search Response

Individual Group Response

Empty Result Set

Integration Patterns

Common Workflows

Related Resources

Include Parameters

Error Handling

Group-Specific Error Scenarios

Troubleshooting Tips

Supported Profiles