Skip to main content
This guide assumes familiarity with building workflows. For an introduction, see How to Build a Workflow. For details on working with input fields, see Fields and Fieldsets.
Filter by Zapier is an app that allows you to add conditional logic to your workflows. With it, you can specify conditions that must be met for the workflow to continue. This is particularly useful when you only want certain data to trigger subsequent actions. For example, only continuing if an email is from a specific sender, or if a lead’s status meets certain criteria. Filter actions work within the standard workflow paradigm described in How to Build a Workflow. While Filter by Zapier is useful enough to warrant its own example, it doesn’t require any special handling compared to other apps and actions.

​
Example: Adding a Filter Step

Let’s walk through an example of adding a filter step to a workflow. We’ll assume you’ve already configured a first step as described in How to Build a Workflow. For this example, let’s say it’s a “New Email in Gmail” trigger.

​
Finding the Filter by Zapier App

First, we need to find the Filter by Zapier app. You can search for it using the GET /v2/apps endpoint: 
GET /v2/apps?query=filter

{
  "data": [
    {
      "id": "e85bcf45-505b-4acb-b7e8-4c3a81d49afb",
      "type": "app",
      "image": "https://zapier-images.imgix.net/storage/services/ad3d7962908c17bcbe753928e8786b4a.png",
      "action_types": [],
      "title": "Filter by Zapier",
      "images": {
        "url_16x16": "https://zapier-images.imgix.net/storage/services/ad3d7962908c17bcbe753928e8786b4a.png?auto=format%2Ccompress&fit=crop&h=16&ixlib=python-3.0.0&q=50&w=16",
        "url_32x32": "https://zapier-images.imgix.net/storage/services/ad3d7962908c17bcbe753928e8786b4a.png?auto=format%2Ccompress&fit=crop&h=32&ixlib=python-3.0.0&q=50&w=32",
        "url_64x64": "https://zapier-images.imgix.net/storage/services/ad3d7962908c17bcbe753928e8786b4a.png?auto=format%2Ccompress&fit=crop&h=64&ixlib=python-3.0.0&q=50&w=64",
        "url_128x128": "https://zapier-images.imgix.net/storage/services/ad3d7962908c17bcbe753928e8786b4a.png?auto=format%2Ccompress&fit=crop&h=128&ixlib=python-3.0.0&q=50&w=128"
      },
      "hex_color": "ff4a00",
      "categories": [
        {
          "slug": "developer-tools"
        },
        {
          "slug": "zapier-tools"
        }
      ],
      "description": "Only allow a Zap to proceed when a certain condition is met. For example, if you're sending a text message when you receive a new email, you could use a Filter that only sends a text message when the email received is from a certain address."
    }
  ]
}
Take note of the app id: e85bcf45-505b-4acb-b7e8-4c3a81d49afb. We’ll use this in the next step.

​
Getting the Filter Action

Now that we have the app ID, we can retrieve the filter action using the GET /v2/actions endpoint with action_type=FILTER: 
GET /v2/actions?app=e85bcf45-505b-4acb-b7e8-4c3a81d49afb&action_type=FILTER

{
  "links": {
    "next": null,
    "prev": null
  },
  "meta": {
    "count": 1,
    "limit": null,
    "offset": null
  },
  "data": [
    {
      "id": "core:example_filter_action_id",
      "key": "filter",
      "app": "e85bcf45-505b-4acb-b7e8-4c3a81d49afb",
      "type": "action",
      "action_type": "FILTER",
      "is_instant": false,
      "title": "Only continue if...",
      "description": "Set up rules to specify when this Zap can continue running."
    }
  ]
}
The filter action has the action_type of FILTER, which distinguishes it from standard READ and WRITE actions.

​
Configuring Filter Inputs

To get the available inputs, make a request to the POST /v2/actions/{action_id}/inputs endpoint: 
// POST /v2/actions/core:example_filter_action_id/inputs
{
  "data": {
    "authentication": null,
    "inputs": {}
  }
}

​
Understanding Filter Criteria

Each fieldset in the response represents a filter condition. A filter condition is a single rule like “email subject contains ‘urgent’” or “lead status equals ‘qualified’”. By default at least one filter condition must be configured. You can increase the number of filter conditions using the filter_criteria_count input.

​
Filter Criteria Count

The filter_criteria_count input controls how many filter conditions are available. Since it has format: "SELECT", we need to fetch its available choices from the POST /v2/actions/{action_id}/inputs/{input_id}/choices endpoint: 
// POST /v2/actions/core:example_filter_action_id/inputs/filter_criteria_count/choices
{
  "data": {
    "authentication": null,
    "inputs": {}
  }
}
You can configure between 1 and 5 filter conditions.

​
Configuring Multiple Filter Conditions

When you set filter_criteria_count to a value greater than 1, you’ll need to refetch the inputs (since invalidates_input_fields is true). Let’s see what happens when we request 2 filter conditions: 
// POST /v2/actions/core:example_filter_action_id/inputs
{
  "data": {
    "authentication": null,
    "inputs": {
      "filter_criteria_count": 2
    }
  }
}
Notice that we now have:
  • A second fieldset (filter_criteria_2)
  • A new boolean_operator input field

​
Boolean Operator

The boolean_operator input appears whenever filter_criteria_count is greater than 1. It determines how multiple filter conditions are combined. Let’s fetch its choices: 
// POST /v2/actions/core:example_filter_action_id/inputs/boolean_operator/choices
{
  "data": {
    "authentication": null,
    "inputs": {}
  }
}
The boolean_operator allows you to specify whether:
  • All conditions must match (and): The workflow continues only if every filter condition is satisfied
  • At least one condition must match (or): The workflow continues if any filter condition is satisfied

​
Filter Match Rules

Each filter condition has a filter_criteria_{n}_match field that determines the comparison method. Since this is a SELECT field, we need to fetch its choices: 
// POST /v2/actions/core:example_filter_action_id/inputs/filter_criteria_1_match/choices
{
  "data": {
    "authentication": null,
    "inputs": {}
  }
}
The available match rules include:
  • Text comparisons: contains, exactly matches, starts with, ends with, etc.
  • Number comparisons: greater than, less than
  • Date/time comparisons: after, before, equals
  • Boolean comparisons: is true, is false
  • Existence checks: exists, does not exist

​
The Key Field

The filter_criteria_{n}_key field must contain one and only one field reference in the format {{previous_step_alias.field_id}} or {{field_id}} (for 2-step workflows). It cannot contain any other text or multiple field references.
For example, if your first step has an alias of gmail_trigger and outputs a field called subject, the key field should be set to: 
"filter_criteria_1_key": "{{gmail_trigger.subject}}"
In a 2-step workflow (where the alias is optional and implicit), you could use: 
"filter_criteria_1_key": "{{subject}}"

​
The Value Field

Depending on the match rule selected for filter_criteria_{n}_match, a filter_criteria_{n}_value field may be returned when you refetch the inputs. This field represents the value to compare against. For example:
  • Match rules like “contains”, “exactly matches”, or “is greater than” require a value to compare against, so filter_criteria_{n}_value will appear
  • Match rules like “exists” or “does not exist” don’t need a comparison value, so filter_criteria_{n}_value will not appear
Since filter_criteria_{n}_match has invalidates_input_fields: true, you’ll need to refetch the inputs after selecting a match rule to see if a value field is required. For more details on this pattern, see the invalidation and dependency flow documentation.

​
Testing a Filter Step

Once you’ve configured the filter inputs, you can test the filter step using the POST /v2/actions/{action_id}/test endpoint. Unlike actual use of the Filter, “raw” values are allowed as there is no prior/incoming field to reference. 
// POST /v2/actions/core:example_filter_action_id/test
{
  "data": {
    "authentication": null,
    "inputs": {
      "filter_criteria_count": 2,
      "boolean_operator": "and",
      "filter_criteria_1_key": "abc",
      "filter_criteria_1_match": "exactly matches",
      "filter_criteria_1_value": "abc",
      "filter_criteria_2_key": "false",
      "filter_criteria_2_match": "is false"
    }
  }
}
The test response includes a can_continue field that indicates whether the filter conditions were met. In this example, both conditions were satisfied, so the workflow would continue.

​
Getting Filter Outputs

To retrieve the output fields from a filter step, use the POST /v2/actions/{action_id}/outputs endpoint: 
// POST /v2/actions/core:example_filter_action_id/outputs
{
  "data": {
    "authentication": null,
    "inputs": {},
    "fetch_live_samples": true
  }
}
Filter steps output a single field: can_continue, which indicates whether the filter conditions were met. While this field can be referenced in subsequent steps, filter steps are typically used for their side effect of halting workflow execution when conditions aren’t met, rather than for their output data.

​
Complete Example

Here’s a complete example of adding a filter step to a workflow. This workflow triggers on new Gmail emails and only continues if the email subject contains “urgent”: 
// POST /v2/zaps
{
  "data": {
    "enabled": true,
    "title": "Process urgent emails only",
    "steps": [
      {
        "action": "core:wJ3PxHpNArZ8MqvloW3L1ZyMDQ4nJ",
        "alias": "gmail_trigger",
        "inputs": {
          "label_id": "INBOX"
        },
        "authentication": "49509"
      },
      {
        "action": "core:example_filter_action_id",
        "alias": "filter_step",
        "authentication": null,
        "inputs": {
          "filter_criteria_count": 1,
          "filter_criteria_1_key": "{{gmail_trigger.subject}}",
          "filter_criteria_1_match": "contains",
          "filter_criteria_1_value": "urgent"
        }
      },
      {
        "action": "core:3ZYFzZKkjbDK2AwQopVqrZWL9pK",
        "inputs": {
          "message": "Urgent email received: {{gmail_trigger.subject}}"
        },
        "authentication": "857610"
      }
    ]
  }
}
Note that filter steps don’t require authentication, so the authentication field is always set to null.
When this workflow runs, step 2 will evaluate whether the email subject contains “urgent”. If it does, the workflow continues to step 3. If it doesn’t, the workflow stops and step 3 never executes.