Understanding Queries: From Basic to Advanced

Building Blocks

The query system is built around two fundamental components:

1. Domain Specification: The company domains you want to find similar matches for
2. Filters: Criteria to narrow down the search results

Every query must include at least one domain in the domains array. Filters are optional but powerful tools to refine your search.

Core Filter Fields

The following fields are available for filtering:

• continent - Geographic region (e.g., "North America", "Europe")
• company_size - Employee count ranges (e.g., "11-50", "51-100")
• country - Specific countries (e.g., "United States", "United Kingdom")
• last_funding_type - Latest funding round (e.g., "Series A", "Seed")

More filters are on the roadmap in near future

Filter Options

Simple Filters

The most basic way to filter is by specifying values for one or more fields:

{
  "domains": ["chattermill.com"],
  "filters": {
    "continent": ["Europe"],
    "company_size": ["11-50"]
  }
}

In simple filters, multiple values for the same field are treated as OR conditions, while different fields are treated as AND conditions.

Understanding OR/AND Operations

The query system supports two logical operators:

• $or - Match any of the conditions
• $and - Match all of the conditions

These can be used explicitly through the operator field in more complex queries.

Simple Query Examples

Single Parameter Query

The most basic query matches companies by a single criterion:

{
  "domains": ["example.com"],
  "filters": {
    "continent": ["Europe"]
  }
}

Multi-Parameter Query

Adding multiple parameters creates an implicit AND condition:

{
  "domains": ["example.com"],
  "filters": {
    "continent": ["Europe"],
    "company_size": ["11-50"],
    "country": ["Germany"]
  }
}

OR Conditional Query

To match any of several conditions, use the $or operator:

{
  "domains": ["example.com"],
  "filters": {
    "operator": "$or",
    "conditions": {
      "continent": ["Europe", "North America"],
      "company_size": ["11-50", "51-100"]
    }
  }
}

AND Conditional Query

For explicit AND conditions, use the $and operator:

{
  "domains": ["example.com"],
  "filters": {
    "operator": "$and",
    "conditions": {
      "continent": ["Europe"],
      "company_size": ["11-50"],
      "last_funding_type": ["Series A"]
    }
  }
}

Complex Nested Queries

Nested AND with OR Conditions

The most complex queries can combine AND and OR conditions at different levels:

{
  "domains": ["example.com"],
  "filters": {
    "operator": "$and",
    "conditions": [
      {
        "operator": "$or",
        "conditions": {
          "continent": ["Europe", "North America"]
        }
      },
      {
        "operator": "$or",
        "conditions": {
          "company_size": ["11-50", "51-100"]
        }
      }
    ]
  }
}

This query finds companies that are:

1. Located in EITHER Europe OR North America
2. AND have EITHER 11-50 OR 51-100 employees

Validation and Error Handling

The API includes robust validation that will:

• Verify all field names are valid
• Ensure values match expected formats
• Validate domain formats
• Check for proper operator usage

If validation fails, you'll receive a 400 response with detailed error messages and suggestions for correction.

{
    "status": "error",
    "message": "Invalid filter configuration",
    "details": {
        "continent": {
            "error": "Invalid continent value",
            "received": "Invalid continent: united kingdom",
            "valid_options": [
                "North America",
                "South America",
                "Europe",
                "Asia",
                "Africa",
                "Oceania",
                "Antarctica"
            ]
        }
    },
    "data": {}
}

Remember:

• All field values must be arrays, even for single values
• Nested conditions must use valid operators ($and/$or)
• Domain names are automatically normalized
• The maximum limit for results is 100