Resource $set-accounts | Medplum

On this page

Medplum implements a custom $set-accounts operation to manage account references. This is the recommended way to manage account references for all resources.

Use Cases

• Multi-Tenant Data Segmentation: Assign resources to specific accounts for organization-based data isolation
• Organization-Based Access Control: Set account references to enable access policies based on organizational membership
• Patient Compartment Management: Propagate account assignments to all resources in a patient's compartment for consistent access
• Batch Account Assignment: Update account references across large sets of resources during migrations or onboarding

This operation sets the target resource's meta.accounts references and optionally propagates changes to resources in that resources's compartment. This is useful when you need to ensure consistent meta.accounts access across all resources related to a patient, for example.

Required access

Calling $set-accounts requires explicit permission to run the operation. Generic read, create, update, or delete access to the target resource type does not automatically grant access to $set-accounts.

If a User, Bot, or ClientApplication receives 403 Forbidden when calling $set-accounts, confirm that the principal's access configuration grants the operation in addition to the resource interactions needed for the target resources.

Warning: It is recommended that you run this operation with Prefer: respond-async header to avoid any timeouts while waiting for resources in patient compartment to update.

For example, when this operation is used to add a new organization to a patient's meta.accounts, it can update both the patient and all resources in the patient's compartment to include a new organization in their meta.accounts lists. Additionally, each resource's meta.compartment will also be updated to include the references in meta.accounts.

Invoke the $set-accounts operation

POST [base]/R4/<ResourceType>/<id>/$set-accounts

Input

The input is a FHIR Parameters resource containing:

• accounts a reference to set in each resource's meta.accounts
• propagate an optional boolean, which instructs the operation to also update resources in the target compartment

Example request payload:

POST /fhir/R4/Patient/f1dc4eed-0b7f-4c23-9059-d4b672cb9177/$set-accounts

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "accounts",
      "valueReference": {
        "reference": "Organization/<organization-id>"
      }
    },
    {
      "name": "accounts",
      "valueReference": {
        "reference": "Practitioner/<practitioner-id>"
      }
    },
    {
      "name": "propagate",
      "valueBoolean": true
    }
  ]
}

Output

The output is a FHIR Parameters resource containing:

• resourcesUpdated The number of resources that were updated

Example response if patient has 3 resources in their compartment:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "resourcesUpdated",
      "valueInteger": 3
    }
  ]
}

• Use Cases
• Required access
• Invoke the $set-accounts operation
  • Input
  • Output