FilterRequest

Advanced Filter Conditions – Nested filter object supporting complex boolean logic.

Structure:

{
  "and": [condition1, condition2, ...],
  "or": [condition1, condition2, ...],
  "not": condition,
  "field": "field_name",
  "operator": "eq|ne|gt|gte|lt|lte|in|nin|like|ilike|is_null|is_not_null",
  "value": "comparison_value"
}

Supported Operators:

• eq – Equals (exact match)
• ne – Not equals
• gt – Greater than
• gte – Greater than or equal
• lt – Less than
• lte – Less than or equal
• in – Value in list
• nin – Value not in list
• like – SQL LIKE pattern matching (case-sensitive)
• ilike – SQL ILIKE pattern matching (case-insensitive)
• is_null – Field is null/empty
• is_not_null – Field has a value

Date Filtering:

• Supports ISO 8601 formats: 2024-01-15T10:30:00Z
• Relative dates: now, today, yesterday
• Date math: now-7d, today+1w, now-1M
• Commonly expressed as a pair of conditions on the same field, e.g. {"field": "created_at", "operator": "gte", "value": "2024-01-01T00:00:00Z"} and {"field": "created_at", "operator": "lte", "value": "2024-03-31T23:59:59Z"}

AND / OR Examples (generic across entities):

{
  "and": [
    {"field": "status", "operator": "eq", "value": 1},
    {"field": "deal_value_amount", "operator": "gte", "value": 50000},
    {
      "or": [
        {"field": "region", "operator": "in", "value": ["EMEA", "NA"]},
        {"field": "owner_id", "operator": "eq", "value": "u-abc-123"}
      ]
    }
  ]
}

This pattern works the same way for deals, companies, leads, people, or any other entity type – only the field names change to match the entity schema.

Note: filters is required but may be an empty object ({}) if you want to apply no filtering and just use sorting / pagination.

Statistical Aggregations – Compute summary metrics alongside filtered results.

Structure:

{
  "aggregation_name": {
    "field": "field_to_aggregate",
    "operation": "count|sum|avg|min|max|distinct_count"
  }
}

Supported Operations:

• count – Count of non-null values
• sum – Sum of numeric values
• avg – Average of numeric values
• min – Minimum value
• max – Maximum value
• distinct_count – Count of unique values

Examples (generic across entities):

{
  "entity_count": {"field": "id", "operation": "count"},
  "total_value": {"field": "deal_value_amount", "operation": "sum"},
  "avg_amount": {"field": "deal_value_amount", "operation": "avg"},
  "max_amount": {"field": "deal_value_amount", "operation": "max"}
}

These names are intentionally generic so the same pattern can be applied to deals, companies, leads, people, or any other entity type.

Use Cases:

• Dashboard metrics and KPIs
• Pipeline / funnel analysis and reporting
• Performance tracking by owner, team, or stage
• Data validation and quality checks

Start date, required when comparePeriod is 'custom' and ignored otherwise.

Comparison timeframe. When set, an entity that records point-in-time figures also returns its totals as they stood at the start of this period, over the same filtered set. Omit it and the response is unchanged. MTD, QTD and YTD follow the account's fiscal calendar; last30Days and last12Months count back from today.

Full-text Search - Search across multiple fields with flexible matching.

Structure:

{
  "term": "search_term",
  "fields": ["field1", "field2", ...],
  "operator": "and|or",
  "case_sensitive": false,
  "exact_match": false
}

Search Options:

• term - Text to search for (required)
• fields - Specific fields to search (optional, defaults to all text fields)
• operator - How to combine multiple terms (and requires all terms, or requires any term)
• case_sensitive - Whether search is case-sensitive (default: false)
• exact_match - Whether to match exact phrases only (default: false)

Searchable Fields:

• name - Deal/entity name
• description - Deal description
• notes - Associated notes
• company_name - Associated company name
• contact_name - Primary contact name
• tags - Associated tags and labels

Examples:

{
  "term": "enterprise software",
  "fields": ["name", "description"],
  "operator": "and",
  "case_sensitive": false
}

Advanced Search:

{
  "term": "Acme Corp Q1 2024",
  "fields": ["name", "company_name"],
  "operator": "or",
  "exact_match": false
}

Use Cases:

• Find deals by company name
• Search deal descriptions for keywords
• Locate deals with specific terms
• Filter by tags or categories

Multi-field Sorting – Sort results by one or more fields with custom directions.

Structure:

[
  {"field": "field_name", "direction": "asc|desc"},
  {"field": "another_field", "direction": "asc|desc"}
]

Sort Directions:

• asc – Ascending order (A–Z, 0–9, oldest first)
• desc – Descending order (Z–A, 9–0, newest first)

Common Fields (vary by entity):

• created_at – Entity creation date
• updated_at – Last modification date
• deal_value_amount – Deal monetary amount field
• status – Lifecycle status
• name – Entity name/title

Examples (generic):

[
  {"field": "deal_value_amount", "direction": "desc"},
  {"field": "created_at", "direction": "asc"}
]

Use Cases:

• Show highest value entities first
• Sort by recency or creation time
• Alphabetical sorting by name
• Combine multiple sort keys for stable ordering