## 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

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

### Input

The input is a [FHIR Parameters](/content/docs/api/fhir/resources/parameters/index.html) 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:

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

```json
{
  "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](/content/docs/api/fhir/resources/parameters/index.html) resource containing:

- `resourcesUpdated` The number of resources that were updated

Example response if patient has 3 resources in their compartment:

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

- [Use Cases](/content/docs/api/fhir/operations/set-accounts#use-cases/index.html)
- [Required access](/content/docs/api/fhir/operations/set-accounts#required-access/index.html)
- [Invoke the `$set-accounts` operation](/content/docs/api/fhir/operations/set-accounts#invoke-the-set-accounts-operation/index.html)
  - [Input](/content/docs/api/fhir/operations/set-accounts#input/index.html)
  - [Output](/content/docs/api/fhir/operations/set-accounts#output/index.html)