# Editing SaaS Datasets

SaaS integration datasets are automatically generated when you configure a SaaS integration. However, you may need to customize these datasets — for example, to add data categories, update field descriptions, or remove fields that are not relevant to your use case.

This guide explains how to edit a SaaS dataset using the Fides API, what changes are allowed, and what happens to your customizations when the integration is updated.

Dataset edits are scoped to a single connection. If you have multiple connections of the same integration type (e.g., two Stripe connections), changes to one connection's dataset will not affect the other. Each connection maintains its own independent dataset.

## Prerequisites 
- A running Fides instance with a [configured SaaS integration](/content/docs/integrations/saas-integrations/index.html)
- The `connection_key` for the connection whose dataset you want to edit
- API access to your Fides instance

## Editing a SaaS dataset via the API 
To update a SaaS dataset, use the `PATCH` endpoint for connection datasets:

```
PATCH /api/v1/connection/{connection_key}/dataset
```

Pass the updated dataset as the request body. For example, to add a data category to a field:

```
[\
  {\
    "fides_key": "my_saas_instance",\
    "collections": [\
      {\
        "name": "user",\
        "fields": [\
          {\
            "name": "email",\
            "data_categories": ["user.contact.email"]\
          }\
        ]\
      }\
    ]\
  }\
]
```

To retrieve the current dataset for reference before editing, use `GET /api/v1/connection/{connection_key}/dataset`.

## Editing rules 
Only the **collections** section of a SaaS dataset is mutable. The following table summarizes what you can and cannot change:

| Action | Allowed? | Notes |
| --- | --- | --- |
| Add or update `data_categories` on a field | Yes |  |
| Add or update the `description` of a field | Yes |  |
| Modify `fides_meta.data_type` on a field | Yes |  |
| Remove a non-protected field | Yes |  |
| Remove a protected field | No | Restored from template automatically |
| Add new collections | No | Ignored during execution, discarded on update |
| Add `references` or `identities` | No | Must be defined in the SaaS config |
| Change top-level metadata (`fides_key`, `name`, `description`, `data_categories`, `organization_fides_key`, `meta`) | No | Restored to original value with a warning |

**Protected fields** are collection fields referenced by the SaaS config (e.g., in `param_values` or `postprocessors`). You can modify their metadata (data categories, descriptions, etc.) but you cannot delete them. To check which fields are protected, use `GET /api/v1/connection/{connection_key}/dataset/{dataset_key}/protected-fields`.

## Behavior on integration update 
When a SaaS integration template is updated, Fides performs a **three-way merge** to reconcile your customizations with the new template. How the update is triggered depends on the template type:

- **Built-in templates** are updated automatically when Fides is upgraded to a version that includes a new template.
- **Custom templates** are only updated when you re-upload the template. A Fides version upgrade will not modify datasets for custom integrations. See [Custom Integration Templates](/content/docs/integrations/guides/custom-integrations#updating-custom-templates/index.html) for details.

In both cases, the merge is performed between your current dataset (with your customizations), the previously stored template (the baseline), and the new template (the update).

| Scenario | Behavior |
| --- | --- |
| You modified a field | Your version is preserved, even if the template also changed it |
| You did not modify a field | Updated to the new template version |
| You deleted a non-protected field | Stays deleted |
| You deleted a protected field | Restored from the new template |
| Template adds a new field | Added to your dataset |
| Template removes a field | Removed from your dataset |

### Example 
Suppose the original template has a `user` collection with fields `email`, `name`, and `product_id`.

**Your edits:**

- Add `data_categories: ["user.contact.email"]` to `email`
- Change the `data_type` on `product_id`
- Delete the `name` field

**New template changes:**

- Changes the `data_type` on `product_id`
- Adds a new `created_at` field

**Result after merge:**

| Field | Outcome |
| --- | --- |
| `email` | Keeps your data category annotation |
| `product_id` | Keeps your `data_type` (your change takes priority) |
| `name` | Remains deleted (not a protected field) |
| `created_at` | Added from the new template |

## Next steps 
- Review the [datasets overview](/content/docs/integrations/guides/datasets/overview/index.html) for general dataset concepts
- Learn how to [create dataset YAML](/content/docs/integrations/guides/datasets/create-dataset-yaml/index.html) for manual dataset definitions
- Explore the [Fides REST API documentation](/content/docs/api-reference/index.html) for the full list of dataset endpoints
- See the [SaaS integrations overview](/content/docs/integrations/saas-integrations/index.html) for details on configuring SaaS connections

[Linking Datasets](/content/docs/integrations/guides/datasets/link-datasets "Linking Datasets"/index.html) [Index](/content/docs/integrations/guides/datasets "Index"/index.html)