Creating and updating leads lists using filters

The endpoint allows you to create or update lists that dynamically filter leads based on specified criteria. Lists are saved with a filter that determines which leads are included.

Basic Payload Request Structure

This is the the basic payload structure:

{
  "id": "existing_list_id",
  "filter": {
    // Filter configuration here
  },
  "name": "My Lead List", 
  "description": "List description",
  "tags": ["hidden", "workflow"]
}

id: optional field. It is a string used for updating existing lists
filter: required field. It is an object used to configure the filters for dynamic list of leads
name: required field. It is a string used to specify the name of the new list
description: optional field. It is a string used to specify the description of the new list
tags: optional field. It is an array of strings used to specify the tags of the new list

Filter Types

The filter field supports four main types of filtering:

1. Global Search

Search across all lead fields:

{
  "name": "All Leads with 'John'",
  "filter": {
    "__global_search__": "John"
  }
}

2. Simple Field Filters

Filter by specific lead properties:

{
  "name": "Job is CTO",
  "filter": {
    "filter": {
      "job": {
        "operator": "equals",
        "valueToCompare": "CTO"
      }
    }
  }
}

3. Logical Combinations (AND/OR)

Combine multiple filters:

{
  "name": "Senior Developers or CTOs",
  "filter": {
    "or": [
      {
        "filter": {
          "job": {
            "operator": "equals",
            "valueToCompare": "CTO"
          }
        }
      },
      {
        "filter": {
          "job": {
            "operator": "contains",
            "valueToCompare": "Senior Developer"
          }
        }
      }
    ]
  }
}

4. Complex Nested Filters

Combine AND/OR with field filters:

{
  "name": "Active Leads in Tech",
  "filter": {
    "and": [
      {
        "filter": {
          "status": {
            "operator": "equals",
            "valueToCompare": "active"
          }
        }
      },
      {
        "or": [
          {
            "filter": {
              "company_industry": {
                "operator": "contains",
                "valueToCompare": "Technology"
              }
            }
          },
          {
            "filter": {
              "company_industry": {
                "operator": "contains",
                "valueToCompare": "Software"
              }
            }
          }
        ]
      }
    ]
  }
}

Available Operators

String Operators

equals / notEquals - Exact match
contains / notContains - Partial match
in / notIn - Match against an array of values

Number Operators

equals / notEquals - Exact match
greaterThan / lowerThan - Numeric comparison
greaterOrEquals / lowerOrEquals - Inclusive comparison
in / notIn - Match against an array of values

Date Operators

beforeDateTime / afterDateTime - Date comparison
Use ISO 8601 format: "2025-02-05T10:54:18.494Z"

Unary Operators

isSet - Field has a value
isNotSet - Field is null/empty

Array Operators

include / includeValueMatching - Array contains value
some / every - Array element matching

Examples

Example 1: Leads with Email

This filter finds all leads with an email.

{
  "name": "Leads with Email",
  "filter": {
    "filter": {
      "email": {
        "operator": "isSet"
      }
    }
  }
}

Example 2: Leads Created After Date

This filter finds all leads which were created after the 1st of July 2025.

{
  "name": "Recent Leads",
  "filter": {
    "filter": {
      "created_at": {
        "operator": "afterDateTime",
        "valueToCompare": "2025-07-01T00:00:00.000Z"
      }
    }
  }
}

Example 3: Multiple Job Titles

This filter finds all the leads whose job title is in the specified list.

{
  "name": "Tech Leadership",
  "filter": {
    "filter": {
      "job": {
        "operator": "in",
        "valueToCompare": ["CTO", "CEO", "VP Engineering", "Technical Director"]
      }
    }
  }
}

Example 4: Complex Filter

This filter finds all the leads where their company size is greater than 100 people and they have an email address and their job title contains either the word Manager or Director.

{
  "name": "High-Value Prospects",
  "filter": {
    "and": [
      {
        "filter": {
          "company_size": {
            "operator": "greaterThan",
            "valueToCompare": 100
          }
        }
      },
      {
        "or": [
          {
            "filter": {
              "job": {
                "operator": "contains",
                "valueToCompare": "Manager"
              }
            }
          },
          {
            "filter": {
              "job": {
                "operator": "contains",
                "valueToCompare": "Director"
              }
            }
          }
        ]
      },
      {
        "filter": {
          "email": {
            "operator": "isSet"
          }
        }
      }
    ]
  }
}

Example 5: Array Filter with 'every' operator

This filter finds all the leads where every skill in their skills array has a level greater than 3. The every operator ensures that all elements in the array match the specified condition.

{
  "name": "Leads with All Skills Required",
  "filter": {
    "filter": {
      "skills": {
        "operator": "every",
        "valueToCompare": {
          "filter": {
            "level": {
              "operator": "greaterThan",
              "valueToCompare": 3
            }
          }
        }
      }
    }
  }
}

Response

The endpoint returns the created/updated list with relevant data:

{
  "id": "list_abc123",
  "name": "My Lead List",
  "description": "Optional description",
  "filter": {
    /* your filter */
  },
  "tags": ["hidden"], // if provided in the payload
  "createdAt": 1704542400000,
  "updatedAt": 1704542400000
}

Advice on endpoint usage

Test filters incrementally - Start with simple filters and build complexity
Use global search for quick text-based filtering across all fields
Combine operators with AND/OR for powerful filtering logic
Check field names - Ensure you're using the correct property names for your leads
Monitor payload size - Keep filters under 3KB for optimal performance