How to Create Custom Feed

Custom Feeds let you automatically segment your web traffic based on specific criteria. Instead of manually filtering through all your website visitors, you can set up feeds that capture exactly the leads you care about—whether that's companies from specific regions, visitors showing buying intent, or traffic from particular campaigns.

This guide explains how advanced filters work and shows you how to build them step by step using the API.

Understanding the Filter Logic

Custom Feeds use a hierarchical structure built from two types of elements:

Filters are individual conditions. Each filter checks one thing: "Is this visitor from a specific region?" or "Did they visit the pricing page?"

Groups combine multiple filters or other groups using logical operators (AND/OR). Groups let you build complex logic like "visitors from Hamburg OR Brandenburg AND who viewed the pricing or demo page."

Think of it like building a sentence: filters are the words, groups are the phrases, and operators connect them together.

How Operators Work

Groups use two operators to combine their contents:

AND means all conditions must be true. Use this when you want to narrow down results: "Show me companies from specific regions AND who viewed intent pages."

OR means at least one condition must be true. Use this when you want to broaden results: "Show me visits to the pricing page OR the demo page."

Critical API Requirements:

The root level group must always use and operator

Root group must contain exactly 2 items

First item: An or group containing your actual filter conditions

Second item: An empty negated or group (placeholder)

Filters must be nested: and → or → and → or → filter

Individual filters use operators like:

is matches exact values

contains finds partial text matches

Other operators: is_not, not_contains, at_least, less_than, begins_with, ends_with, is_empty, is_present

The Negation Pattern

You can flip any filter or group to mean the opposite by adding "negated": true. This turns "companies from region X" into "companies NOT from region X."

Available Filter Fields

The API documentation shows these filter fields in working examples:

Geographic: region, country_code
Behavior: page_url

Note: The full list of available filter fields is documented in Custom Feed Filter Reference.

Filter Structure Pattern

The API enforces this specific nested structure:

{
  "type": "group",
  "operator": "and",
  "items": [
    {
      "type": "group",
      "operator": "or",
      "negated": false,
      "items": [
        {
          "type": "group",
          "operator": "and",
          "items": [
            {
              "type": "group",
              "operator": "or",
              "items": [
                { "type": "filter", "field": "...", "operator": "...", "value": "..." }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "group",
      "operator": "or",
      "negated": true,
      "items": []
    }
  ]
}

Key Rules:

Root level: and group with exactly 2 items

First item: or group containing your conditions

Second item: Empty negated or group (required placeholder)

Filters nest as: and → or → and → or → filter

The nesting alternates operators: and → or → and → or

Three Working Examples

These examples use only fields documented in the official API examples.

Example 1: Simple Regional Filter

Use case: You want to track traffic from a specific region.

{
  "data": {
    "type": "custom_feed",
    "attributes": {
      "name": "Hamburg Traffic",
      "notifications": [],
      "advanced_filters": {
        "type": "group",
        "operator": "and",
        "items": [
          {
            "type": "group",
            "operator": "or",
            "items": [
              {
                "type": "group",
                "operator": "and",
                "items": [
                  {
                    "type": "group",
                    "operator": "or",
                    "items": [
                      {
                        "type": "filter",
                        "operator": "is",
                        "field": "region",
                        "value": "Hamburg"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "group",
            "operator": "or",
            "negated": true,
            "items": []
          }
        ]
      }
    }
  }
}

How it works: The filter at the deepest level checks if region equals "Hamburg". The structure follows the API's required pattern with alternating and/or groups. The second empty negated group is a required placeholder.

Example 2: Multiple Regions (OR Logic)

Use case: You want to track visitors from multiple regions.

{
  "data": {
    "type": "custom_feed",
    "attributes": {
      "name": "Hamburg or Brandenburg",
      "notifications": [],
      "advanced_filters": {
        "type": "group",
        "operator": "and",
        "items": [
          {
            "type": "group",
            "operator": "or",
            "items": [
              {
                "type": "group",
                "operator": "and",
                "items": [
                  {
                    "type": "group",
                    "operator": "or",
                    "items": [
                      {
                        "type": "filter",
                        "operator": "is",
                        "field": "region",
                        "value": "Hamburg"
                      },
                      {
                        "type": "filter",
                        "operator": "is",
                        "field": "region",
                        "value": "Brandenburg"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "group",
            "operator": "or",
            "negated": true,
            "items": []
          }
        ]
      }
    }
  }
}

How it works: The innermost or group contains two filters. If region is Hamburg OR Brandenburg, the visit matches.

Example 3: Combining Geography and Behavior (AND Logic)

Use case: You want to track visitors from specific regions who also showed buying intent by visiting conversion pages.

This is the example shown in the official API documentation.

{
  "data": {
    "type": "custom_feed",
    "attributes": {
      "name": "Hamburg/Brandenburg – Clean Intent Traffic",
      "notifications": [],
      "advanced_filters": {
        "type": "group",
        "operator": "and",
        "items": [
          {
            "type": "group",
            "operator": "or",
            "items": [
              {
                "type": "group",
                "operator": "and",
                "items": [
                  {
                    "type": "group",
                    "operator": "or",
                    "items": [
                      {
                        "type": "filter",
                        "operator": "is",
                        "field": "region",
                        "value": "Hamburg"
                      },
                      {
                        "type": "filter",
                        "operator": "is",
                        "field": "region",
                        "value": "Brandenburg"
                      }
                    ]
                  },
                  {
                    "type": "group",
                    "operator": "or",
                    "items": [
                      {
                        "type": "filter",
                        "operator": "contains",
                        "field": "page_url",
                        "value": "pricing"
                      },
                      {
                        "type": "filter",
                        "operator": "contains",
                        "field": "page_url",
                        "value": "demo"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "group",
            "operator": "or",
            "negated": true,
            "items": []
          }
        ]
      }
    }
  }
}

How it works: The middle and group combines two separate or groups:

Region is Hamburg OR Brandenburg (first group)

Page URL contains "pricing" OR "demo" (second group)

Both conditions must be true for a visit to match. This AND-of-ORs pattern is how you build sophisticated targeting.

Building Your Filter Strategy

Start with Your Business Goal

Before writing any code, define what you're trying to achieve. Are you:

Qualifying inbound leads by geography?

Tracking campaign performance?

Identifying accounts showing buying signals?

Filtering specific traffic patterns?

Your goal determines which fields matter and how to combine them.

Build from Simple to Complex

Don't try to create your final filter in one pass. Start with one dimension, verify it works, then layer on additional criteria:

Start with one filter (Example 1)

Add multiple options with OR (Example 2)

Combine dimensions with AND (Example 3)

Add exclusions using negation

Test Your Logic

The easiest way to verify a filter is to create it and then query visits using the Search Web Visits endpoint. If you get unexpected results, simplify the filter until you find what's not working.

Additional Features

Organizing with Folders

Feeds can be organized into folders. First, retrieve available folders:

Then reference the folder when creating your feed:

{
  "relationships": {
    "folder": {
      "id": "17",
      "type": "custom_feed_folder"
    }
  }
}

Setting Up Notifications

Get alerts when visits match your feed criteria:

{
  "notifications": [
    {
      "sending_interval": "day",
      "medium": "email",
      "user_id": 12345
    }
  ]
}

Available intervals: immediate for real-time alerts, day for daily digests, or week for weekly summaries.

Common Pitfalls

Wrong root operator or structure: The root group must ALWAYS use and operator. The error "value at /operator is not: and" means you didn't use and at the root level.

Missing the second placeholder group: The root and group requires exactly 2 items. The second must be an empty negated or group.

Using is instead of contains for URLs: URLs often include path parameters or tracking codes. Use contains to match the core path rather than requiring an exact match.

Using non-existent filter fields: Check Custom Feed Filter Reference for a listing of all available filters.

Not testing with real data: Theoretical filters often behave differently than expected. Always test against actual visit data.

Making Changes to Existing Feeds

Use the PATCH endpoint to update feed configuration:

You can modify the name, filters, notifications, or folder assignment. The feed ID stays the same, so any integrations referencing it keep working.

Understanding the Filter Logic#

How Operators Work#

The Negation Pattern#

Available Filter Fields#

Filter Structure Pattern#

Three Working Examples#

Example 1: Simple Regional Filter#

Example 2: Multiple Regions (OR Logic)#

Example 3: Combining Geography and Behavior (AND Logic)#

Building Your Filter Strategy#

Start with Your Business Goal#

Build from Simple to Complex#

Test Your Logic#

Additional Features#

Organizing with Folders#

Setting Up Notifications#

Common Pitfalls#

Making Changes to Existing Feeds#