# Update filter

`PUT /v1/operations/filters/{filterId}`

Available as MCP tool `update-filter` (Replace).

Filter endpoints allow you to review and manage filters for async messages. A filter can contain multiple rules, but you can only create one filter per subscription. [Learn about filters](https://docs.redoxengine.com/permalink/Zn8kiEw3GdyBFaSwQNSAN).

You can retrieve, create, update, or delete filters, as well as review and manage filter links.  

### Update filter

Update an existing filter in the specified environment. When you update a filter, it automatically applies to traffic where it's linked.  

> **Recommendation about PHI in filters**
>
> If you choose to filter fields with PHI, users assigned to an <u>**observer**</u> role might unintentionally access confidential data. Keep in mind that access to filter contents is managed by a different permission from the one managing access to log payloads.

## Request parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `filterId` | path | string | Yes | Displays the unique identifier of the filter. |

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Contains the human-readable name of the asset. |
| `action` | string | Yes | Defines what action should be performed when the filter is applied to a message. Possible values: block-all, send |
| `rules` | Array of object | Yes | Contains a list of rules that determine when the filter is applied to a message. A filter is only applied if ALL rules are met. |
| `rules[].path` | string | No | Specifies the path to the field(s) that should be evaluated when the filter is applied. This should be a `jsonpath` value. |
| `rules[].values` | Array of string | No | Contains an array of string values that are matched against the path value when the rule is evaluated. |
| `rules[].allowList` | boolean | No | Indicates whether the rule is an allow-list (matches when the value at the specified path is in the values array) or a deny-list (matches when the value at the specified path is NOT in the values array). Defaults to `true` (allow-list). |

## Request example

_Generated from the schema: the values are placeholders, not a real payload._

```bash
curl 'https://api.redoxengine.com/platform/v1/operations/filters/{filterId}' \
--request PUT \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
  "name": "string",
  "action": "send",
  "rules": [
    {
      "path": "$.Patient.Demographics.FirstName",
      "values": [
        "string"
      ],
      "allowList": true
    }
  ]
}'
```

## Responses

### 200

Contains a payload object with the details for the requested filter.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `meta` | object | No |  |
| `meta.version` | string | No | Lists the major and minor version number for the format of the returned payload. The payload format or shape may change between minor versions, like including additional or extended fields in later versions. We include the version data in each response so that you have the option to handle the signaled differences. |
| `payload` | object | No |  |
| `payload.filter` | object | No | Contains a filter and its related details. |
| `payload.filter.usage` | Array of object | No | Contains details about where the filter is being used. |
| `payload.filter.usage[].linkId` | string (uuid) | No | Contains the unique identifier of the link for a specified asset. |
| `payload.filter.usage[].organization` | object | No | Describes the Redox organization that the asset belongs to. |
| `payload.filter.usage[].organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filter.usage[].organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.filter.usage[].connectingOrganization` | object | No | Specifies the organization the asset is connected to when the subscription relates to a partner organization. |
| `payload.filter.usage[].connectingOrganization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filter.usage[].connectingOrganization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.filter.usage[].subscription` | object | No |  |
| `payload.filter.usage[].subscription.id` | string (uuid) | No | Contains the unique identifier of the subscription. |
| `payload.filter.usage[].subscription.dataModel` | string | No | Specifies the Redox data model that the link applies to or should apply to. |
| `payload.filter.usage[].subscription.source` | object | No | Specifies the source of the subscription that an asset is or should be linked to. |
| `payload.filter.usage[].subscription.source.id` | string (uuid) | Yes | Contains the unique identifier of the source. |
| `payload.filter.usage[].subscription.source.name` | string, nullable | No | Specifies the name of the source. |
| `payload.filter.usage[].subscription.destination` | object | No | Specifies the destination of the subscription that an asset is or should be linked to. |
| `payload.filter.usage[].subscription.destination.id` | string (uuid) | Yes | Contains the unique identifier of the destination. |
| `payload.filter.usage[].subscription.destination.name` | string, nullable | No | Specifies the name of the destination. |
| `payload.filter.usage[].filterId` | string (uuid) | No | Contains the unique identifier of the asset being linked. |
| `payload.filter.usage[].version` | string | No | Contains the API schema version used for this asset. |
| `payload.filter.usage[].eventType` | string, nullable | No | Specifies the specific event type for a data model that the link applies to or should apply to. |
| `payload.filter.usage[].createdAt` | string | No | Displays the date and time that the asset was originally created in ISO 8601 format. |
| `payload.filter.usage[].createdBy` | object | No | Contains the metadata about the user who created the asset. |
| `payload.filter.usage[].createdBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.usage[].createdBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.usage[].updatedAt` | string | No | Displays the date and time that the asset was last updated in ISO 8601 format. |
| `payload.filter.usage[].updatedBy` | object | No | Contains the metadata about the user who last updated the asset. |
| `payload.filter.usage[].updatedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.usage[].updatedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.usage[].deletedAt` | string, nullable | No | Displays the date and time that the asset was deleted. Returns a `null` value if the asset hasn't been deleted. |
| `payload.filter.usage[].deletedBy` | object, nullable | No | Contains the metadata about the user who deleted the asset. |
| `payload.filter.usage[].deletedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.usage[].deletedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.promotionAssociations` | Array of object | No | Contains a list of promotions associated with this asset. |
| `payload.filter.promotionAssociations[].organization` | object | No | Describes the Redox organization that the asset belongs to. |
| `payload.filter.promotionAssociations[].organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filter.promotionAssociations[].organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.filter.promotionAssociations[].fromAsset` | object | No | Describes the original asset that was created in staging and promoted to production. |
| `payload.filter.promotionAssociations[].fromAsset.id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.filter.promotionAssociations[].fromAsset.environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.filter.promotionAssociations[].fromAsset.environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.filter.promotionAssociations[].fromAsset.type` | string | No | Possible values: configModifier, filter, translationSet |
| `payload.filter.promotionAssociations[].fromAsset.latestVersion` | number | No | Displays the most recent version of the original asset in staging. This may vary from the version number in production. A different version number may indicate you need to re-promote the asset to production. |
| `payload.filter.promotionAssociations[].toAsset` | object | No | Describes the promoted asset that can be used or linked to subscriptions in production. |
| `payload.filter.promotionAssociations[].toAsset.id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.filter.promotionAssociations[].toAsset.environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.filter.promotionAssociations[].toAsset.environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.filter.promotionAssociations[].toAsset.type` | string | No | Possible values: configModifier, filter, translationSet |
| `payload.filter.promotionAssociations[].toAsset.latestVersion` | number | No | Displays the most recent version of the promoted asset in production. This may vary from the version number in staging. A different version number may indicate you need to re-promote the staging asset to production. |
| `payload.filter.promotionAssociations[].toAsset.outOfDate` | boolean | No | Indicates whether the version of the promoted asset in production is different from the version of the original asset in staging. |
| `payload.filter.promotionAssociations[].createdAt` | string | No | Displays the date and time that the asset was originally created in ISO 8601 format. |
| `payload.filter.promotionAssociations[].createdBy` | object | No | Contains the metadata about the user who created the asset. |
| `payload.filter.promotionAssociations[].createdBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.promotionAssociations[].createdBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.promotionAssociations[].updatedAt` | string | No | Displays the date and time that the asset was last updated in ISO 8601 format. |
| `payload.filter.promotionAssociations[].updatedBy` | object | No | Contains the metadata about the user who last updated the asset. |
| `payload.filter.promotionAssociations[].updatedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.promotionAssociations[].updatedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.promotionAssociations[].deletedAt` | string, nullable | No | Displays the date and time that the asset was deleted. Returns a `null` value if the asset hasn't been deleted. |
| `payload.filter.promotionAssociations[].deletedBy` | object, nullable | No | Contains the metadata about the user who deleted the asset. |
| `payload.filter.promotionAssociations[].deletedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.promotionAssociations[].deletedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.filter.name` | string | No | Contains the human-readable name of the asset. |
| `payload.filter.rules` | Array of object | No | Contains a list of rules that determine when the filter is applied to a message. A filter is only applied if ALL rules are met. |
| `payload.filter.rules[].path` | string | No | Specifies the path to the field(s) that should be evaluated when the filter is applied. This should be a `jsonpath` value. |
| `payload.filter.rules[].values` | Array of string | No | Contains an array of string values that are matched against the path value when the rule is evaluated. |
| `payload.filter.rules[].allowList` | boolean | No | Indicates whether the rule is an allow-list (matches when the value at the specified path is in the values array) or a deny-list (matches when the value at the specified path is NOT in the values array). Defaults to `true` (allow-list). |
| `payload.filter.action` | string | No | Defines what action should be performed when the filter is applied to a message. Possible values: block-all, send |
| `payload.filter.pathType` | string | No | Specifies the format of the field paths defined for this filter's rules. Both FHIR and data model filters use the `jsonpath` path type. Value: jsonpath |
| `payload.filter.version` | string | No | Contains the API schema version used for this asset. |
| `payload.filter.filterVersion` | number | No | Contains the numeric version of the asset. Version numbers start at 1 and increment in whole numbers whenever the asset is updated. |
| `payload.filter.createdAt` | string | No | Displays the date and time that the asset was originally created in ISO 8601 format. |
| `payload.filter.createdBy` | object | No | Contains the metadata about the user who created the asset. |
| `payload.filter.createdBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.createdBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.updatedAt` | string | No | Displays the date and time that the asset was last updated in ISO 8601 format. |
| `payload.filter.updatedBy` | object | No | Contains the metadata about the user who last updated the asset. |
| `payload.filter.updatedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.updatedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.deletedAt` | string, nullable | No | Displays the date and time that the asset was deleted. Returns a `null` value if the asset hasn't been deleted. |
| `payload.filter.deletedBy` | object, nullable | No | Contains the metadata about the user who deleted the asset. |
| `payload.filter.deletedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filter.deletedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filter.environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.filter.environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.filter.organization` | object | No | Describes the Redox organization that the asset belongs to. |
| `payload.filter.organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filter.organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |

_Generated from the schema: the values are placeholders, not a real payload._

```json
{
  "meta": {
    "version": "1.0.0"
  },
  "payload": {
    "filter": {
      "usage": [
        {
          "linkId": "009f739c-6620-43b0-978e-b245e723c57a",
          "organization": {
            "id": 122,
            "name": "string"
          },
          "connectingOrganization": {
            "id": 122,
            "name": "string"
          },
          "subscription": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "dataModel": "PatientAdmin",
            "source": {
              "name": "string",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "destination": {
              "name": "string",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            }
          },
          "filterId": "aff0ee0f-f371-4b82-82c6-dc3b96f05c91",
          "version": "1.0.0",
          "eventType": "string",
          "createdAt": "2024-04-25T18:17:16.719Z",
          "createdBy": {
            "id": 0,
            "name": "string"
          },
          "updatedAt": "2024-04-25T18:17:16.719Z",
          "updatedBy": {
            "id": 0,
            "name": "string"
          },
          "deletedAt": "2024-04-25T18:17:16.719Z",
          "deletedBy": {
            "id": 0,
            "name": "string"
          }
        }
      ],
      "promotionAssociations": [
        {
          "organization": {
            "id": 122,
            "name": "string"
          },
          "fromAsset": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "environment": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "type": "configModifier",
            "latestVersion": 0
          },
          "toAsset": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "environment": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            },
            "type": "configModifier",
            "latestVersion": 0,
            "outOfDate": true
          },
          "createdAt": "2024-04-25T18:17:16.719Z",
          "createdBy": {
            "id": 0,
            "name": "string"
          },
          "updatedAt": "2024-04-25T18:17:16.719Z",
          "updatedBy": {
            "id": 0,
            "name": "string"
          },
          "deletedAt": "2024-04-25T18:17:16.719Z",
          "deletedBy": {
            "id": 0,
            "name": "string"
          }
        }
      ],
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "rules": [
        {
          "path": "$.Patient.Demographics.FirstName",
          "values": [
            "string"
          ],
          "allowList": true
        }
      ],
      "action": "send",
      "pathType": "jsonpath",
      "version": "1.0.0",
      "filterVersion": 2,
      "createdAt": "2024-04-25T18:17:16.719Z",
      "createdBy": {
        "id": 0,
        "name": "string"
      },
      "updatedAt": "2024-04-25T18:17:16.719Z",
      "updatedBy": {
        "id": 0,
        "name": "string"
      },
      "deletedAt": "2024-04-25T18:17:16.719Z",
      "deletedBy": {
        "id": 0,
        "name": "string"
      },
      "environment": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      },
      "organization": {
        "id": 122,
        "name": "string"
      }
    }
  }
}
```

### 400

Bad Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.id` | string | No | Contains a unique identifier for the given error instance. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Bad Request`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Bad Request",
      "code": "validation.error.bad.request",
      "detail": "Error details",
      "status": 400,
      "transient": false
    }
  }
}
```

### 403

Forbidden

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.errors` | Array of object | No |  |
| `payload.errors[].title` | string | No | Displays the high-level error message, typically something succinct like `Forbidden`. |
| `payload.errors[].code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |

```json
{
  "payload": {
    "errors": [
      {
        "title": "Forbidden",
        "code": "authorization.forbidden"
      }
    ]
  }
}
```

### 500

Internal Server Error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Failed in step X`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Internal Server Error",
      "code": "failed.db.lookup",
      "detail": "Error details",
      "status": 500,
      "transient": true
    }
  }
}
```
